@salesforce/webapp-template-app-react-sample-b2e-experimental 1.82.0 → 1.84.0

package/dist/.a4drules/skills/webapp-ui-ux/scripts/search.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+
+import { CSV_CONFIG, AVAILABLE_STACKS, MAX_RESULTS, search, searchStack } from './core.js';
+import { generateDesignSystem } from './design_system.js';
+
+// ============ ARG PARSER ============
+
+function parseArgs(argv) {
+  const args = { query: null, maxResults: MAX_RESULTS, format: 'ascii' };
+  let i = 2;
+  while (i < argv.length) {
+    const a = argv[i];
+    if (a === '--domain' || a === '-d') { args.domain = argv[++i]; }
+    else if (a === '--stack' || a === '-s') { args.stack = argv[++i]; }
+    else if (a === '--max-results' || a === '-n') { args.maxResults = parseInt(argv[++i], 10); }
+    else if (a === '--json') { args.json = true; }
+    else if (a === '--design-system' || a === '-ds') { args.designSystem = true; }
+    else if (a === '--project-name' || a === '-p') { args.projectName = argv[++i]; }
+    else if (a === '--format' || a === '-f') { args.format = argv[++i]; }
+    else if (a === '--persist') { args.persist = true; }
+    else if (a === '--page') { args.page = argv[++i]; }
+    else if (a === '--output-dir' || a === '-o') { args.outputDir = argv[++i]; }
+    else if (!a.startsWith('-') && !args.query) { args.query = a; }
+    i++;
+  }
+  return args;
+}
+
+// ============ FORMATTER ============
+
+function formatOutput(result) {
+  if (result.error) return `Error: ${result.error}`;
+
+  const lines = [];
+  if (result.stack) {
+    lines.push('## UI Pro Max Stack Guidelines');
+    lines.push(`**Stack:** ${result.stack} | **Query:** ${result.query}`);
+  } else {
+    lines.push('## UI Pro Max Search Results');
+    lines.push(`**Domain:** ${result.domain} | **Query:** ${result.query}`);
+  }
+  lines.push(`**Source:** ${result.file} | **Found:** ${result.count} results\n`);
+
+  (result.results || []).forEach((row, i) => {
+    lines.push(`### Result ${i + 1}`);
+    for (const [key, value] of Object.entries(row)) {
+      const v = String(value);
+      lines.push(`- **${key}:** ${v.length > 300 ? v.slice(0, 300) + '...' : v}`);
+    }
+    lines.push('');
+  });
+
+  return lines.join('\n');
+}
+
+// ============ MAIN ============
+
+const args = parseArgs(process.argv);
+
+if (!args.query) {
+  console.error('Usage: node search.js "<query>" [--domain <d>] [--stack <s>] [--design-system] [-p "Name"]');
+  console.error(`Domains: ${Object.keys(CSV_CONFIG).join(', ')}`);
+  console.error(`Stacks: ${AVAILABLE_STACKS.join(', ')}`);
+  process.exit(1);
+}
+
+if (args.designSystem) {
+  const result = generateDesignSystem(
+    args.query,
+    args.projectName,
+    args.format,
+    !!args.persist,
+    args.page || null,
+    args.outputDir || null
+  );
+  console.log(result);
+
+  if (args.persist) {
+    const slug = args.projectName ? args.projectName.toLowerCase().replace(/\s+/g, '-') : 'default';
+    console.log('\n' + '='.repeat(60));
+    console.log(`✅ Design system persisted to design-system/${slug}/`);
+    console.log(`   📄 design-system/${slug}/MASTER.md (Global Source of Truth)`);
+    if (args.page) {
+      const pageSlug = args.page.toLowerCase().replace(/\s+/g, '-');
+      console.log(`   📄 design-system/${slug}/pages/${pageSlug}.md (Page Overrides)`);
+    }
+    console.log('');
+    console.log(`📖 Usage: When building a page, check design-system/${slug}/pages/[page].md first.`);
+    console.log(`   If exists, its rules override MASTER.md. Otherwise, use MASTER.md.`);
+    console.log('='.repeat(60));
+  }
+} else if (args.stack) {
+  const result = searchStack(args.query, args.stack, args.maxResults);
+  console.log(args.json ? JSON.stringify(result, null, 2) : formatOutput(result));
+} else {
+  const result = search(args.query, args.domain, args.maxResults);
+  console.log(args.json ? JSON.stringify(result, null, 2) : formatOutput(result));
+}

package/dist/.a4drules/skills/webapp-unsplash-images/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: webapp-unsplash-images
+description: Adds high-quality Unsplash images to React pages. Use when the user asks to add a hero image, background image, placeholder image, stock photo, decorative image, or any Unsplash-sourced imagery to the web application.
+---
+
+# Unsplash Images
+
+## When to Use
+
+Use this skill when:
+- Adding hero banners, section backgrounds, or decorative images
+- The user asks for stock photography or placeholder images
+- A page needs visual appeal without custom assets
+
+---
+
+## Step 1 — Determine image purpose
+
+Identify what the image is for:
+
+- **Hero / banner** — full-width background behind text or a CTA
+- **Section accent** — smaller image alongside content (stats, testimonials, features)
+- **Card thumbnail** — image inside a card component
+- **Background texture** — subtle decorative background
+
+If unclear, ask:
+
+> "Where should the image appear — as a hero banner, a section accent, or a card thumbnail?"
+
+---
+
+## Step 2 — Select the right Unsplash URL format
+
+Read `implementation/usage.md` for the full reference. Key rules:
+
+1. **Always use `images.unsplash.com/photo-{id}` format** with explicit `w` and `q` parameters.
+2. **Never use `source.unsplash.com`** — it is deprecated and returns 404s.
+3. **Pin every image by its photo ID** — never rely on random or search endpoints.
+
+---
+
+## Step 3 — Validate image URLs
+
+Before using any Unsplash URL in code:
+
+1. Open the URL in a browser or fetch it to confirm it returns a 200 status and a valid image.
+2. If the URL returns a 404, redirect loop, or broken image, **discard it** and pick a different photo ID.
+3. Never ship a URL you have not personally verified.
+
+---
+
+## Step 4 — Implementation
+
+Read `implementation/usage.md` and follow the instructions there.
+
+---
+
+## Verification
+
+Before completing:
+
+1. Confirm every Unsplash URL loads a valid image (no 404, no redirect loops).
+2. Confirm `alt` text is set appropriately (empty `alt=""` for decorative, descriptive for meaningful).
+3. Run from the web app directory:
+
+```bash
+cd force-app/main/default/webapplications/<appName> && npm run lint && npm run build
+```
+
+- **Lint:** MUST result in 0 errors.
+- **Build:** MUST succeed.

package/dist/.a4drules/skills/webapp-unsplash-images/implementation/usage.md

@@ -0,0 +1,159 @@
+# Unsplash Images — Implementation Guide
+
+## URL Format
+
+Always use the direct `images.unsplash.com` format with explicit sizing:
+
+```
+https://images.unsplash.com/photo-{PHOTO_ID}?w={WIDTH}&q={QUALITY}
+```
+
+| Parameter | Purpose | Recommended values |
+|-----------|---------|--------------------|
+| `w` | Pixel width served by the CDN | `600` card, `800` section, `1200` hero, `1920` full-bleed |
+| `q` | JPEG quality 1–100 | `80`–`85` (good balance of quality vs size) |
+
+### Deprecated / broken formats — do NOT use
+
+| Format | Why it fails |
+|--------|-------------|
+| `source.unsplash.com/random` | Deprecated; returns 404 |
+| `source.unsplash.com/{WIDTH}x{HEIGHT}` | Deprecated; returns 404 |
+| `source.unsplash.com/featured/?{query}` | Deprecated; returns 404 |
+
+---
+
+## How to find a valid photo ID
+
+1. Go to [unsplash.com](https://unsplash.com) and search for the subject (e.g. "modern apartment").
+2. Open a photo. The URL will look like `unsplash.com/photos/{slug}-{PHOTO_ID}` or `unsplash.com/photos/{PHOTO_ID}`.
+3. The `PHOTO_ID` is the last hyphen-separated segment (e.g. `photo-1600596542815-ffad4c1539a9`).
+4. Build your URL: `https://images.unsplash.com/photo-1600596542815-ffad4c1539a9?w=1200&q=85`
+5. **Test the URL** in a browser before committing.
+
+---
+
+## Declaring image constants
+
+Define all Unsplash URLs as named constants at the top of the file. Never inline URLs in JSX.
+
+```tsx
+const HERO_IMAGE = "https://images.unsplash.com/photo-1600596542815-ffad4c1539a9?w=1200&q=85";
+const SECTION_IMAGE = "https://images.unsplash.com/photo-1514565131-fce0801e5785?w=800&q=85";
+```
+
+---
+
+## Rendering images in JSX
+
+### Hero / banner (decorative — empty alt)
+
+```tsx
+<div className="relative w-full overflow-hidden rounded-2xl">
+  <div className="relative aspect-[21/9] min-h-[280px] w-full md:aspect-[3/1]">
+    <img
+      src={HERO_IMAGE}
+      alt=""
+      className="h-full w-full object-cover"
+      loading="eager"
+      fetchPriority="high"
+    />
+    <div className="absolute inset-0 bg-black/40" />
+    <div className="absolute inset-0 flex flex-col items-center justify-center px-4">
+      {/* overlay content */}
+    </div>
+  </div>
+</div>
+```
+
+Key points:
+- `alt=""` for decorative images (screen readers skip them).
+- `loading="eager"` and `fetchPriority="high"` for above-the-fold heroes.
+- `object-cover` prevents stretching.
+- Semi-transparent overlay (`bg-black/40`) ensures text readability.
+
+### Section accent (meaningful — descriptive alt)
+
+```tsx
+<div className="relative min-h-[240px] overflow-hidden rounded-2xl">
+  <img src={SECTION_IMAGE} alt="City skyline at sunset" className="h-full w-full object-cover" />
+  <div className="absolute inset-0 bg-gradient-to-r from-black/20 to-transparent" />
+</div>
+```
+
+### Card thumbnail
+
+```tsx
+<div className="aspect-[4/3] overflow-hidden bg-muted">
+  <img
+    src={imageUrl}
+    alt=""
+    className="h-full w-full object-cover transition-transform hover:scale-105"
+    loading="lazy"
+  />
+</div>
+```
+
+Key points:
+- `loading="lazy"` for below-the-fold images.
+- `hover:scale-105` subtle zoom on hover.
+- `bg-muted` fallback color while loading.
+
+---
+
+## Fallback when no image is available
+
+Always provide a placeholder when the image URL may be null:
+
+```tsx
+{imageUrl ? (
+  <img src={imageUrl} alt="" className="h-full w-full object-cover" />
+) : (
+  <div className="flex h-full items-center justify-center text-muted-foreground">
+    No image
+  </div>
+)}
+```
+
+---
+
+## Content Security Policy (CSP)
+
+If the application enforces CSP headers, add `images.unsplash.com` to `img-src`:
+
+```
+img-src 'self' https://images.unsplash.com;
+```
+
+Other commonly needed origins for stock images:
+
+| Origin | Purpose |
+|--------|---------|
+| `images.unsplash.com` | Unsplash photos |
+| `images.pexels.com` | Pexels photos |
+| `fonts.googleapis.com` | Google Fonts CSS |
+| `fonts.gstatic.com` | Google Fonts files |
+
+---
+
+## Accessibility checklist
+
+- [ ] Decorative images have `alt=""`
+- [ ] Meaningful images have descriptive `alt` text
+- [ ] Hero images use `loading="eager"` and `fetchPriority="high"`
+- [ ] Below-fold images use `loading="lazy"`
+- [ ] Text over images has sufficient contrast (use overlay like `bg-black/40`)
+- [ ] All URLs verified to return a valid image (no 404s)
+
+---
+
+## Common mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Using `source.unsplash.com` | Replace with `images.unsplash.com/photo-{id}?w=…&q=…` |
+| Hardcoding an unverified URL | Open URL in browser first; replace if broken |
+| Missing `w` parameter | Always set width — CDN returns full-res (5000px+) otherwise |
+| `loading="lazy"` on hero | Use `loading="eager"` for above-the-fold images |
+| No fallback for nullable URLs | Wrap in conditional with placeholder div |
+| Inline URLs in JSX | Extract to named constants at file top |

package/dist/.a4drules/webapp-no-node-e.md

@@ -1,26 +1,65 @@
 ---
-description: No node -e - use replace_in_file or write_to_file only
+description: No complex node -e one-liners — use temp .js files or sed/awk instead
 paths:
   - "force-app/main/default/webapplications/**/*"
 ---
 
-# A4D Enforcement: No node -e
+# A4D Enforcement: No `node -e` One-Liners
 
-This project forbids using "node -e" for any operation (file manipulation, string replacement, reading/writing configs, shell automation).
+This project **forbids** using `node -e` (or `node -p`, `node --eval`) one-liners for any operation—file manipulation, string replacement, reading/writing configs, or shell automation.
 
-Policy:
-- Never use "node -e" one-liners.
-- Use replace_in_file or write_to_file for code/config edits.
-- Use jq/sed/awk cautiously when needed; prefer replace_in_file for deterministic edits.
-- For JSON edits: prefer write_to_file after reading, or replace_in_file with precise diffs.
-- For ESLint/TS config changes: edit files directly via write_to_file or replace_in_file.
+## Why This Exists
 
-Rationale:
-- Ensures reproducibility and auditability.
-- Avoids shell escaping bugs and cross-platform inconsistencies.
-- Aligns with project reliability protocol.
+Complex `node -e '...'` one-liners **silently break in Zsh** (the default macOS shell) because of:
 
-Violation handling:
-- If any prior step used "node -e", revert and redo using write_to_file or replace_in_file.
+- **`!` (history expansion):** Zsh interprets `!` inside double quotes as history expansion, causing `event not found` errors or silent corruption.
+- **Backtick interpolation:** Template literals (`` ` ``) are interpreted as command substitution by the shell before Node.js ever sees them.
+- **Nested quoting:** Multi-line JS crammed into a single shell string requires fragile quote escaping that differs between Bash and Zsh.
+
+These failures are **silent and intermittent**—the command may appear to succeed while producing corrupt output.
+
+## What To Do Instead
+
+### For multi-line file edits or transforms
+
+1. **Write a temporary `.js` script**, run it, then delete it:
+
+```bash
+cat > /tmp/_transform.js << 'SCRIPT'
+const fs = require('fs');
+const data = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+data.name = 'my-app';
+fs.writeFileSync('package.json', JSON.stringify(data, null, 2) + '\n');
+SCRIPT
+node /tmp/_transform.js && rm /tmp/_transform.js
+```
+
+2. **Use `sed` or `awk`** for simple, single-pattern replacements with careful escaping:
+
+```bash
+sed -i '' 's/old-value/new-value/g' path/to/file
+```
+
+3. **Use `jq`** for JSON edits:
+
+```bash
+jq '.name = "my-app"' package.json > tmp.json && mv tmp.json package.json
+```
+
+4. **Use the IDE/agent file-editing tools** (replace_in_file, write_to_file, StrReplace, Write) whenever available—these bypass the shell entirely.
+
+### For simple, truly one-line expressions
+
+A trivial `node -e "console.log(1+1)"` with no special characters is acceptable, but **if the expression contains any of these, use a temp file instead:**
+- Template literals (backticks)
+- `!` characters
+- Nested quotes
+- Multi-line strings
+- `fs` read/write operations
+
+## Violation Handling
+
+- If any prior step used a complex `node -e` one-liner, **revert and redo** using one of the approved methods above.
+- If a shell command fails with `event not found`, `unexpected token`, or produces garbled output, check for a `node -e` violation first.
 
 **Cross-reference:** This rule is also summarized in **webapp.md** (MUST FOLLOW #1). Both apply.

package/dist/.a4drules/webapp-react.md

@@ -45,21 +45,20 @@ Use standard web APIs and npm packages only.
 
 ## Data Access (CRITICAL)
 
-### Use DataSDK for All Salesforce API Calls
+All Salesforce API calls **must** go through the DataSDK (`@salesforce/sdk-data`). Do NOT use `axios` or raw `fetch` — the SDK handles authentication and CSRF.
 
-```typescript
-import { getDataSDK } from '@salesforce/sdk-data';
+### GraphQL (Preferred)
 
-const sdk = await getDataSDK();
-// Use sdk.graphql?.() or sdk.fetch!() for API calls
-```
+For queries and mutations, follow the **`graphql-data-access`** skill in `feature-graphql`. It covers schema exploration, query patterns, codegen, type generation, and guardrails.
 
-Do NOT use `axios` or raw `fetch` for Salesforce APIs. The SDK handles authentication and CSRF.
+### UI API (Fallback)
 
-### Data Access Priority
+When GraphQL cannot cover the use case, use `sdk.fetch!()` for UI API endpoints:
 
-1. **GraphQL** (preferred) — queries & mutations via `sdk.graphql?.()`
-2. **UI API** — via `sdk.fetch!()` for `/services/data/v62.0/ui-api/*`
+```typescript
+const sdk = await getDataSDK();
+const resp = await sdk.fetch!('/services/data/v62.0/ui-api/records/{recordId}');
+```
 
 ### Apex REST is NOT Available
 

package/dist/.a4drules/webapp-skills-first.md

@@ -0,0 +1,26 @@
+---
+description: Always search for and read relevant skills before starting any task
+paths:
+  - "force-app/main/default/webapplications/**/*"
+---
+
+# Skills-First Protocol (MUST FOLLOW)
+
+**Before writing any code or executing any command**, search for relevant skills that may already provide guidance, patterns, or step-by-step instructions for the task at hand.
+
+## Core Directive
+Before planning, executing a task, generating code, or running terminal commands, you MUST explicitly check if an existing Skill is available to handle the request. Do not default to manual implementation if a specialized domain Skill exists.
+
+## Pre-Task Sequence
+1. **Skill Discovery:** Review the names and descriptions of all available/loaded Skills in your current context.
+2. **Match Analysis:** Evaluate if the user's current task aligns with any Skill's described use case (e.g., code reviews, PR generation, database migrations, specific framework debugging).
+3. **Explicit Declaration:** If a matching Skill is found, your first output MUST be:
+   > "Skill identified: [Skill Name]. Executing via Skill instructions..."
+   You must then strictly adhere to the instructions defined in that specific Skill.
+
+## Prohibited Actions
+* Do not write custom utility scripts or complex bash commands for a workflow that is already covered by a loaded Skill.
+* Do not bypass or ignore the loaded `SKILL.md` instructions if a relevant Skill is triggered.
+
+## Manual Fallback
+Only proceed with standard/manual execution if you have actively evaluated your available Skills and confirmed that no relevant Skill exists for the current prompt.

package/dist/.a4drules/webapp.md

@@ -4,6 +4,10 @@ paths:
   - "force-app/main/default/webapplications/**/*"
 ---
 
+# Skills-First (MUST FOLLOW)
+
+**Before writing any code or running any command**, search for relevant skills (`SKILL.md` files) that cover your task. Read the full skill and follow its instructions. Skills live in `.a4drules/skills/` and `feature/*/skills/`. See **webapp-skills-first.md** for the full protocol and a task-to-skill lookup table.
+
 # Web App Generation
 
 ## Before `sf webapp generate`
@@ -75,6 +79,10 @@ Agents consistently miss these. **You must not leave them default.**
 - **Motion:** Use high-impact motion (e.g. staggered reveals).
 - **Depth:** Add atmosphere/depth in backgrounds.
 
+# Shell Command Safety (MUST FOLLOW)
+
+**Never use complex `node -e` one-liners** for file edits or multi-line transforms. They break in Zsh due to `!` history expansion and backtick interpolation. Use a temporary `.js` file, `sed`/`awk`, `jq`, or IDE file-editing tools instead. See **webapp-no-node-e.md** for full details and approved alternatives.
+
 # Development Cycle
 
 - Execute tasks continuously until all planned items complete in the current iteration.

package/dist/AGENT.md

@@ -26,6 +26,8 @@ Used for SFDX metadata (LWC, Aura, etc.). Scripts here are for the base SFDX tem
 | `npm run prettier` | Format supported metadata files |
 | `npm run prettier:verify` | Check Prettier |
 
+**One-command setup:** From project root run `node scripts/setup-cli.mjs --target-org <alias>` to run login (if needed), deploy, optional permset/data import, GraphQL schema/codegen, web app build, and optionally the dev server. Use `node scripts/setup-cli.mjs --help` for options (e.g. `--skip-login`, `--skip-data`, `--webapp-name`).
+
 Root **does not** run the React app. The root `npm run build` is a no-op for the base SFDX project.
 
 ### 2. React web app (where you do most work)

package/dist/CHANGELOG.md

@@ -3,6 +3,28 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [1.84.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.83.0...v1.84.0) (2026-03-09)
+
+
+### Features
+
+* **template:** add setup-cli and prepare-import-unique-fields scripts ([#240](https://github.com/salesforce-experience-platform-emu/webapps/issues/240)) ([5cad14c](https://github.com/salesforce-experience-platform-emu/webapps/commit/5cad14c9be8176b2faf2429fe8e8a56383aac1ae))
+
+
+
+
+
+# [1.83.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.82.0...v1.83.0) (2026-03-09)
+
+
+### Features
+
+* dedupe with feature skills, rename to webapp-react-* where relevant @W-21338965@ ([#233](https://github.com/salesforce-experience-platform-emu/webapps/issues/233)) ([9e4e4d8](https://github.com/salesforce-experience-platform-emu/webapps/commit/9e4e4d80f4a33575412e1940a8cbfaae6c035a12))
+
+
+
+
+
 # [1.82.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.81.0...v1.82.0) (2026-03-09)
 
 **Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental

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

@@ -15,9 +15,9 @@
     "graphql:schema": "node scripts/get-graphql-schema.mjs"
   },
   "dependencies": {
-    "@salesforce/agentforce-conversation-client": "^1.82.0",
-    "@salesforce/sdk-data": "^1.82.0",
-    "@salesforce/webapp-experimental": "^1.82.0",
+    "@salesforce/agentforce-conversation-client": "^1.84.0",
+    "@salesforce/sdk-data": "^1.84.0",
+    "@salesforce/webapp-experimental": "^1.84.0",
     "@tailwindcss/vite": "^4.1.17",
     "@tanstack/react-form": "^1.28.4",
     "class-variance-authority": "^0.7.1",
@@ -42,7 +42,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.82.0",
+    "@salesforce/vite-plugin-webapp-experimental": "^1.84.0",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.1.0",
     "@testing-library/user-event": "^14.5.2",

package/dist/force-app/main/default/webapplications/appreactsampleb2e/webapplication.json

@@ -2,6 +2,6 @@
   "outputDir": "dist",
   "routing": {
     "trailingSlash": "never",
-    "fallback": "/index.html"
+    "fallback": "index.html"
   }
 }

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/webapp-template-base-sfdx-project-experimental",
-  "version": "1.82.0",
+  "version": "1.84.0",
   "description": "Base SFDX project template",
   "private": true,
   "files": [
@@ -18,7 +18,8 @@
     "test:unit:coverage": "sfdx-lwc-jest --coverage",
     "prettier": "prettier --write \"**/*.{cls,cmp,component,css,html,js,json,md,page,trigger,xml,yaml,yml}\"",
     "prettier:verify": "prettier --check \"**/*.{cls,cmp,component,css,html,js,json,md,page,trigger,xml,yaml,yml}\"",
-    "precommit": "lint-staged"
+    "precommit": "lint-staged",
+    "setup": "node scripts/setup-cli.mjs"
   },
   "devDependencies": {
     "@lwc/eslint-plugin-lwc": "^2.0.0",