@salesforce/webapp-template-feature-react-chart-experimental 1.48.0 → 1.48.2

package/README.md

@@ -67,7 +67,7 @@ You can test the extension of the base app and the components via the following:
 
 ```bash
 npm run build   # apply patches → dist
-npm run dev     # run from dist
+npm run start   # run from dist
 npm run watch   # watch and re-apply
 ```
 

package/dist/.a4drules/README.md

@@ -0,0 +1,35 @@
+# A4D Rules Index
+
+Rules in this folder guide the agent for this SFDX project. **Knowledge** (expert content) lives in the **local-expert MCP** repo (e.g. `local-expert-mcp`); rules here reference when to call which expert.
+
+## Always-apply rules (MUST follow)
+
+| File | Purpose |
+|------|--------|
+| **webapp.md** | Main web app rules: invoke local-expert MCP (`webapplications-design-system` + `webapplications`), no `node -e`, React/SFDX workflow; **replace default boilerplate**; **populate home page**; **frontend aesthetics**—avoid AI slop, follow design-system expert. |
+| **webapp-no-node-e.md** | No `node -e` for any file/config/shell work; use `replace_in_file` or `write_to_file` only. |
+| **a4d-webapp-generate.md** | Before `sf webapp generate`: call `get_expert_knowledge` with `webapplications-design-system` and `webapplications`; then run CLI. |
+| **webapp-ui-first.md** | Build UI (layout, components, styling) first; then implement business logic (APIs, state, handlers). |
+| **webapp-nav-and-placeholders.md** | **Build navigation into the app layout** (`appLayout.tsx`). Always update nav menu (app-specific items/labels) and placeholder name/design (header/nav/footer/title). Often missed—mandatory. |
+
+## Context-specific rules (by file pattern or topic)
+
+| File | Purpose |
+|------|--------|
+| **react.md** | React web app structure, shadcn/Tailwind, data access, security; edit `appLayout.tsx` when changing layout. |
+| **ui-layout.md** | When changing UI/nav/header/footer/sidebar/theme, always update `appLayout.tsx`. |
+| **code-quality.md** | ESLint, Prettier, import order, naming, lint/build before completion; no `node -e`. |
+| **build-validation.md** | `npm run build` must succeed from web app dir before completing. |
+| **typescript.md** | TypeScript strictness, return types, interfaces. |
+| **images.md** | Images: Unsplash default, CSP, alt text, error handling. |
+| **react_image_processing.md** | Image handling (Unsplash, CSP, accessibility) for React components. |
+| **graphql/** | GraphQL tools and knowledge (schemas, LDS guides). |
+
+## Knowledge repository (experts)
+
+Expert knowledge is served by the **local-expert MCP** (e.g. at `local-expert-mcp`). The agent must call **`get_expert_knowledge`** with the appropriate topic:
+
+- **webapplications-design-system** — Always use for web app UI/design work (design system, typography, color, motion).
+- **webapplications** — Use for app generation and structure; then call sub-topics as needed (e.g. `webapplications-best-practice`, `webapplications-feature-*`).
+
+See the MCP repo's **rule-expert-mcp.md** for full topic list and when to call which expert.

package/dist/.a4drules/a4d-webapp-generate.md

@@ -0,0 +1,27 @@
+---
+description: A4D rule — call expert MCP (webapplications + webapplications-design-system) before sf webapp generate
+alwaysApply: true
+---
+
+# A4D Rule: Before `sf webapp generate`
+
+Before running **`sf webapp generate`**, you **must**:
+
+1. **Call the expert MCP** (`get_expert_knowledge`) with topic **`webapplications-design-system`** — always invoke this expert for UI/design direction.
+2. **Call the expert MCP** with topic **`webapplications`** to get generation and structure guidance.
+3. Follow the instructions from the MCP responses.
+4. Only after that, run `sf webapp generate` (e.g. `sf webapp generate -n <AppName> -t <template>`).
+
+**Webapp name (`-n` / `<AppName>`):** Must be **alphanumerical only**—no spaces, hyphens, underscores, or other special characters. Use only letters (A–Z, a–z) and digits (0–9). If the desired name has spaces or special characters, use a single alphanumeric word (e.g. `CoffeeBoutique` instead of `Coffee Boutique` or `coffee-boutique`).
+
+Do not run `sf webapp generate` without having invoked the expert MCP with **`webapplications-design-system`** and **`webapplications`** first.
+
+When modifying an existing web app (UI, layout, or new features), **always** call `get_expert_knowledge` with topic **`webapplications-design-system`** before making UI or design changes.
+
+**After generating (or when touching a new app):** Replace all default boilerplate content (e.g. "React App", "Vite + React", default document title in `index.html`, placeholder text in the shell) with the actual app name or user-facing copy. Do not leave generic template text in the UI or `<title>`.
+
+**Home page content:** Populate the home page (root route) with real, app-specific content (e.g. landing section, banners, tiles, hero, links to features). Never leave the home page as the default template or placeholder.
+
+**Navigation menu and placeholder name/design:** After generating or when delivering a web app, **you must** (1) **Edit the navigation menu** in `appLayout.tsx`: replace every default nav item and label with app-specific routes and names; do not leave template "Home"/"About" or placeholder links. (2) **Replace the placeholder app name** in the header, nav brand, footer, and `index.html` `<title>` with the actual app name. (3) **Update placeholder design** in the shell (header/footer/branding) so it is not the template default. See **webapp-nav-and-placeholders.md**. Agents often skip this—do not.
+
+Prioritize webapplications generation first, and then generate the metadata.

package/dist/.a4drules/build-validation.md

@@ -8,16 +8,16 @@ Build validation for successful deployments with minimal friction.
 
 ## MANDATORY: Build Success
 
-**Before completing any coding session:**
+**Before completing any coding session** (from the web app directory `force-app/main/default/webapplications/<appName>/`):
 ```bash
 npm run build  # MUST succeed with no errors
 ```
 
 ## Quick Quality Checks
+Run from the web app directory (`force-app/main/default/webapplications/<appName>/`):
 ```bash
-npm run format:check  # Auto-fixable
-npm run lint          # Most issues auto-fixable
-tsc -b               # Catches major issues
+npm run lint   # ESLint; fix issues before completing
+npm run build  # Runs tsc -b && vite build; catches TypeScript and build issues
 ```
 
 ## Requirements
@@ -29,14 +29,12 @@ tsc -b               # Catches major issues
 
 **Can Be Warnings:**
 - ESLint warnings
-- Prettier formatting issues
 - Minor TypeScript warnings
 
-## Auto-Fix Commands
+## Fix Commands (when available in the web app's package.json)
 ```bash
-npm run fix-all      # Fix formatting + linting
-npm run format       # Fix Prettier issues
-npm run lint:fix     # Fix ESLint issues
+npm run lint         # Run ESLint (always available)
+# If your project adds Prettier/format scripts, use those before completing
 ```
 
 ## Workflow
@@ -47,8 +45,8 @@ npm run lint:fix     # Fix ESLint issues
 3. Check periodically: `npm run lint` (optional)
 
 **Before Completion:**
-1. Run `npm run build`
-2. If fails: Run `npm run fix-all`, fix TypeScript errors, retry build
+1. Run `npm run build` from the web app directory
+2. If it fails: fix TypeScript/ESLint errors (run `npm run lint`), then retry build
 
 ## Error Priority
 
@@ -59,7 +57,6 @@ npm run lint:fix     # Fix ESLint issues
 
 **Fix When Convenient:**
 - ESLint warnings
-- Prettier formatting
 - Unused variables
 
 ## Hard Requirements
@@ -67,11 +64,11 @@ npm run lint:fix     # Fix ESLint issues
 - No broken imports
 - Basic TypeScript type safety
 
-## Key Commands
+## Key Commands (web app directory)
 ```bash
-npm run dev          # Start development
-npm run build        # Check deployment readiness
-npm run fix-all      # Fix common issues
+npm run start        # Start development server (vite)
+npm run build        # TypeScript + Vite build; check deployment readiness
+npm run lint         # Run ESLint
 ```
 
 ## Troubleshooting Import Errors

package/dist/.a4drules/code-quality.md

@@ -2,38 +2,27 @@
 
 Enforces ESLint, Prettier, and coding best practices for consistent, maintainable code.
 
+**Execution rule:** Do not use `node -e` for any file or config edits. Use `replace_in_file` or `write_to_file` only (see **webapp-no-node-e.md**).
+
 ## Targets
 - `force-app/main/default/webapplications/*/**/*`
 - `**/*.{js,ts,jsx,tsx,json,md}`
 
 ## MANDATORY Checks
 
-**Before writing code:**
+**Before completing code** (run from the web app directory `force-app/main/default/webapplications/<appName>/`):
 ```bash
-npm run lint         # MUST result in: 0 problems (0 errors, 0 warnings)
-npm run format:check # MUST result in: All matched files use Prettier code style!
+npm run lint   # MUST result in: 0 errors (0 warnings preferred)
+npm run build  # MUST succeed (includes TypeScript check)
 ```
 
-## Prettier Config (.prettierrc)
-```json
-{
-  "semi": true,
-  "trailingComma": "es5",
-  "singleQuote": true,
-  "printWidth": 80,
-  "tabWidth": 2,
-  "useTabs": false,
-  "bracketSpacing": true,
-  "arrowParens": "avoid",
-  "endOfLine": "lf"
-}
-```
+If your project adds Prettier, use a consistent config (e.g. `.prettierrc` with `semi`, `singleQuote`, `printWidth`, etc.) and run format checks before completing.
+
+## Lint / Fix
 
-## Auto-Fix Commands
 ```bash
-npm run fix-all      # Fix formatting + linting (recommended)
-npm run format       # Fix Prettier issues
-npm run lint:fix     # Fix ESLint issues
+npm run lint   # Run ESLint (always available in the template web app)
+# Use your editor's format-on-save or add npm scripts for Prettier if desired
 ```
 
 ## Import Order (MANDATORY)
@@ -139,12 +128,10 @@ const DEBOUNCE_DELAY = 5000; // Correct
 ## Quality Workflow
 
 **Before Committing:**
-1. `npm run check-all` - All checks must pass
-2. `npm run fix-all` - Auto-fix issues if needed
-3. `npm run build` - Build must succeed
+1. `npm run lint` - 0 errors (and 0 warnings when possible)
+2. `npm run build` - Build must succeed (TypeScript + Vite)
 
 ## Zero Tolerance Policy
 - ESLint errors: MUST be 0
-- ESLint warnings: MUST be 0
-- Prettier violations: MUST be 0
-- TypeScript errors: MUST be 0
+- ESLint warnings: MUST be 0 (fix when convenient)
+- TypeScript errors: MUST be 0 (enforced by `npm run build`)

package/dist/.a4drules/graphql.md

@@ -3,22 +3,23 @@
 Instructs agents to use the established GraphQL utilities for Salesforce data access.
 
 ## Targets
-- `force-app/main/default/webApplications/static-app/**/*.ts`
-- `force-app/main/default/webApplications/static-app/**/*.tsx`
+- `force-app/main/default/webapplications/<appName>/**/*.ts`
+- `force-app/main/default/webapplications/<appName>/**/*.tsx`
 
 ## TypeScript Types & Code Generation
 
 ### Generated Types File
-Types are auto-generated at: `force-app/main/default/webApplications/static-app/src/api/graphql-operations-types.ts`
+Types are auto-generated at: `force-app/main/default/webapplications/<appName>/src/api/graphql-operations-types.ts`
 
 ### Generation Command
+Run from the web app directory (replace `<appName>` with your app folder name, e.g. `base-react-app`):
 ```bash
-cd force-app/main/default/webApplications/static-app && npm run graphql:codegen
+cd force-app/main/default/webapplications/<appName> && npm run graphql:codegen
 ```
 
-The codegen configuration is located at `scripts/graphql/codegen.js` and generates types from:
-- Schema: `schema.graphql` (root level)
-- Documents: `force-app/main/default/webApplications/static-app/src/**/*.{graphql,ts,tsx}`
+The codegen configuration is located at `scripts/graphql/codegen.js` (or the package's codegen config) and generates types from:
+- Schema: `schema.graphql` (root level of the web app or as configured)
+- Documents: `force-app/main/default/webapplications/<appName>/src/**/*.{graphql,ts,tsx}`
 
 ### Type Naming Convention
 For a GraphQL operation named `GetHighRevenueAccounts`:
@@ -28,7 +29,7 @@ For a GraphQL operation named `GetHighRevenueAccounts`:
 ## Core Types & Function Signatures
 
 ### executeGraphQL Function
-Located in `force-app/main/default/webApplications/static-app/src/api/graphql.ts`:
+Located in `force-app/main/default/webapplications/<appName>/src/api/graphql.ts`:
 
 ```typescript
 function executeGraphQL<T, InputVariables = Record<string, unknown>>(
@@ -118,7 +119,7 @@ There are **two acceptable patterns** for defining GraphQL queries:
 Store queries in `.graphql` files for codegen to process:
 
 ```graphql
-# force-app/main/default/webApplications/static-app/src/api/utils/query/myQuery.graphql
+# force-app/main/default/webapplications/<appName>/src/api/utils/query/myQuery.graphql
 query GetMyData($myVariable: String) {
   uiapi {
     query {
@@ -137,7 +138,7 @@ query GetMyData($myVariable: String) {
 
 #### Step 2: Run Code Generation
 ```bash
-cd force-app/main/default/webApplications/static-app && npm run graphql:codegen
+cd force-app/main/default/webapplications/<appName> && npm run graphql:codegen
 ```
 
 This generates types in `graphql-operations-types.ts`:
@@ -254,7 +255,7 @@ export async function getCurrentUser(): Promise<User | null> {
 ## Reference Examples
 
 ### Pattern 1 Example: accounts.ts
-See `force-app/main/default/webApplications/static-app/src/api/utils/accounts.ts` for Pattern 1:
+See `force-app/main/default/webapplications/<appName>/src/api/utils/accounts.ts` for Pattern 1:
 1. Importing query from `.graphql` file with `?raw` suffix
 2. Importing generated types from `graphql-operations-types.ts`
 3. Using `NodeOfConnection` to extract node types
@@ -262,7 +263,7 @@ See `force-app/main/default/webApplications/static-app/src/api/utils/accounts.ts
 5. Safe data extraction from the nested response
 
 ### Pattern 2 Example: user.ts
-See `force-app/main/default/webApplications/static-app/src/api/utils/user.ts` for Pattern 2:
+See `force-app/main/default/webapplications/<appName>/src/api/utils/user.ts` for Pattern 2:
 1. Using `gql` template tag for inline query definition
 2. Importing generated types from `graphql-operations-types.ts`
 3. Simple query without variables
@@ -279,7 +280,7 @@ For dynamic fieldsets with known fields that should be conditionally included, u
 
 ### Example with Fragments
 ```graphql
-# static-app/src/api/utils/query/getAccountDetails.graphql
+# <appName>/src/api/utils/query/getAccountDetails.graphql
 query GetAccountDetails(
   $id: ID!
   $includeFinancials: Boolean!

package/dist/.a4drules/react.md

@@ -17,17 +17,27 @@ Apply these rules to the React web app files under the SFDX package directory:
 - Standardize UI with shadcn/ui and Tailwind.
 - Prevent prohibited patterns that break React or Salesforce constraints.
 
+## UI / layout edits (MANDATORY — read before any UI change)
+
+**When the user asks for UI changes** (new components, pages, navigation, header, footer, sidebar, theme, or “layout”):  
+**You MUST open and update `src/appLayout.tsx`** (the theme layout) whenever the change affects how the app shell looks or behaves.  
+Do not only edit pages or components and leave `appLayout.tsx` unchanged.  
+If in doubt, **edit appLayout.tsx as well**.  
+The layout file is: `force-app/main/default/webapplications/<appName>/src/appLayout.tsx` (or the app’s `appLayout.tsx` used by `routes.tsx`).
+
+**Navigation menu and placeholder name/design:** In `appLayout.tsx`, always replace the **default navigation menu** (items and labels) with app-specific links and names, and replace the **placeholder app name** (header, nav brand, footer) and **placeholder design** with the actual app name and intentional styling. Do not leave template nav or "React App"–style branding. See **webapp-nav-and-placeholders.md**.
+
 ## Project & Entry Points
 
 - React web app root: `force-app/main/default/webapplications/<appName>/`
 - Main entry component: `force-app/main/default/webapplications/<appName>/src/App.tsx`
-- Running Development Server:
-  - `npm run dev`
+- **Theme/layout shell**: `force-app/main/default/webapplications/<appName>/src/appLayout.tsx` — wraps all routed content (navigation, header, sidebar, outlet). Routes use `<AppLayout />` as the layout element; page content renders inside it via `<Outlet />`. When making UI edits that affect global layout, navigation, header, footer, sidebar, or theme, **you must consider and edit appLayout.tsx** in addition to page or component files; do not only edit individual pages and omit the layout.
+- Running Development Server (from the web app directory):
+  - `npm run start` — starts the Vite dev server
   - You can generally assume the dev server is already running and don't need to start it.
-- Keep build/deploy workflow intact:
-  - `npm run build`
-  - `npm run deploy`
-  - `npm run open`
+- Build (from the web app directory):
+  - `npm run build` — TypeScript check + Vite build
+- Deploy and open in Salesforce are done from the **SFDX project root** (e.g. via Salesforce CLI or the IDE), not via the web app's package.json. Keep the app buildable so deploy workflows continue to work.
 
 ## Component Library (MANDATORY)
 
@@ -45,6 +55,20 @@ import { Input } from '@/components/ui/input';
 - Use Tailwind CSS utility classes.
 - Follow consistent spacing, color, and typography conventions.
 
+## React & TypeScript Standards
+
+- Component Architecture: Prefer functional components with hooks.
+- File Naming: Use PascalCase for components (e.g., `Button.tsx`) and camelCase for hooks (e.g., `useAuth.ts`).
+- Imports: Use absolute paths (e.g., `@/components/...`) if the `tsconfig.json` or `vite.config.ts` supports it.
+- State: Default to `useState` for local state; avoid adding global state libraries unless requested.
+
+## Layout and theme (appLayout.tsx) — CRITICAL for UI edits
+
+- **appLayout.tsx** is the application shell: it wraps every page and typically contains the main navigation (e.g. `NavigationMenu`), header, sidebar, and `<Outlet />` for child routes. It defines the global look and structure of the app.
+- **MANDATORY:** When asked to change the UI in ways that affect the **overall layout**, **navigation**, **header**, **footer**, **sidebar**, or **theme** (e.g. add a top bar, change nav items, add a sidebar, apply a theme wrapper), you **MUST** edit `appLayout.tsx` (or the app’s layout file) as part of the same change. Do not only edit individual pages or components and leave the layout unchanged.
+- **Before finishing any UI edit:** Ask yourself: “Does this touch layout, nav, header, footer, sidebar, or theme?” If yes, **you must have modified appLayout.tsx** (or the layout file used by routes). If you did not, add that edit before considering the task done.
+- If the project uses feature inheritance (e.g. `__inherit__appLayout`), the editable layout may live in the app or feature at `src/appLayout.tsx`; ensure you modify the correct file that is actually used by `routes.tsx`.
+
 ## Module & Platform Restrictions
 
 - React apps must NOT import or rely on Salesforce platform modules; do not use:
@@ -281,6 +305,7 @@ async function safeFetch(recordId) {
 
 ## Anti-Patterns (Do NOT do these)
 
+- **Do NOT make UI/layout/theme/nav changes without updating appLayout.tsx** — If you add or change navigation, header, footer, sidebar, or overall layout, you must also edit the layout shell (`src/appLayout.tsx`). Leaving appLayout.tsx untouched while editing only pages or components is an error.
 - **Apex REST is not available in React applications** - Do NOT attempt to use or call Apex REST endpoints from React code
 - Unnecessary Apex controllers for simple UI API/GraphQL operations
 - Missing error handling for async operations
@@ -352,7 +377,8 @@ function sanitizeInput(input) {
 
 ## Quality Checklist (for generated code)
 
-- Entry point maintained (`App.js` present and wired in pages).
+- Entry point maintained (`App.tsx` or `App.js` present and wired in routes/pages).
+- **Layout maintained (MANDATORY for UI work):** For any change that affects global layout, nav, header, footer, sidebar, or theme, you **must** have edited `appLayout.tsx`. If you did not open or modify appLayout.tsx, the change is incomplete — go back and update the layout file.
 - Uses shadcn/ui and Tailwind for UI.
 - Follows Data Access rules with proper auth and error handling.
 - Enforces Security standards and input sanitization.

package/dist/.a4drules/ui-layout.md

@@ -0,0 +1,23 @@
+# UI layout: always update appLayout.tsx (MANDATORY)
+
+**Build navigation into the app layout:** The app layout (e.g. `appLayout.tsx`) must **include** the navigation—header nav, sidebar, or both—so that every routed page is wrapped by the same shell and nav. Do not omit nav from the layout or rely on per-page nav only.
+
+## Targets (File Pattern Matching)
+
+Apply this rule when editing React UI or layout:
+
+- `force-app/main/default/webapplications/*/src/appLayout.tsx`
+- `force-app/main/default/webapplications/*/src/**/*.tsx`
+- `force-app/main/default/webapplications/*/src/**/*.jsx`
+
+## Rule (CRITICAL)
+
+**When making any UI change** that affects navigation, header, footer, sidebar, theme, or overall layout:
+
+1. **You MUST also edit `src/appLayout.tsx`** (the theme layout used by `routes.tsx`).
+2. Do not only edit pages or components and leave `appLayout.tsx` unchanged.
+3. Before finishing: confirm you opened and modified `appLayout.tsx` if the change touches layout/nav/theme. If you did not, the task is incomplete — update the layout file.
+
+**Navigation menu and placeholder name/design (often missed):** When editing the layout, **always** update (1) the **navigation menu**—replace default nav items and labels with app-specific links and names; do not leave template "Home"/"About" or placeholder links; (2) the **app name** in header/nav brand/footer and in `index.html` `<title>`—use the actual app name, not the template placeholder; (3) any **placeholder design** in the shell so it matches the app. See **webapp-nav-and-placeholders.md**.
+
+Path: `force-app/main/default/webapplications/<appName>/src/appLayout.tsx` (or the app's layout file that `routes.tsx` imports). (or the app’s layout file that `routes.tsx` imports).

package/dist/.a4drules/webapp-nav-and-placeholders.md

@@ -0,0 +1,33 @@
+---
+description: A4D rule — always update navigation menu and placeholder name/design; never leave default
+alwaysApply: true
+---
+
+# Navigation Menu & Placeholder Name/Design (MANDATORY)
+
+Agents consistently miss these. **You must not leave them default.**
+
+**Navigation belongs in the app layout:** Build the navigation **into** the app layout (e.g. `appLayout.tsx`). The layout component must include the nav—header nav, sidebar, or both—so every page is wrapped by the same shell and nav. Do not omit navigation from the layout or put it only on individual pages.
+
+## 1. Navigation menu
+
+- **Always edit the navigation menu** in the layout file (typically `src/appLayout.tsx`). Replace default/placeholder nav items and labels with **app-specific** links and names.
+- Do **not** leave template items (e.g. "Home", "About", generic links or placeholder labels). Use real routes and labels that match the app (e.g. "Dashboard", "Products", "Orders" for an e‑commerce app).
+- The navigation is part of the app shell; it lives in **appLayout.tsx** (or the file that `routes.tsx` uses as the layout). Open that file and update every nav link and label.
+
+**Check before finishing:** Did I change the nav items and labels in the layout file to match this app? If not, the task is incomplete.
+
+## 2. Placeholder name and design
+
+- **Replace the placeholder app name** everywhere it appears: header, nav brand/logo area, footer, document `<title>`, and any "Welcome to…" or generic title text. Use the **actual app name** (e.g. the name used in `sf webapp generate -n <AppName>` or the user's requested name).
+- **Replace placeholder design** in the shell: default header/footer styling, generic logo area, and any template branding must be updated to match the app's aesthetic (or at least use the real app name and intentional styling).
+
+**Check before finishing:** Is the app name and shell design still the template default anywhere? If yes, update it.
+
+## Where to edit
+
+- **Layout/nav/branding:** `force-app/main/default/webapplications/<appName>/src/appLayout.tsx` — the app layout must contain the navigation (build it in here).
+- **Document title:** `force-app/main/default/webapplications/<appName>/index.html`
+- **Root page content:** The component rendered at the root route (often `Home` or similar in `routes.tsx`)
+
+Completing a web app task includes updating **navigation menu**, **app name in header/nav/footer/title**, and **placeholder design** in the shell—not only the main page content.

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

@@ -0,0 +1,25 @@
+---
+description: A4D rule — no node -e; use replace_in_file / write_to_file only
+alwaysApply: true
+---
+
+# A4D Enforcement: No node -e
+
+This project forbids using "node -e" for any operation (file manipulation, string replacement, reading/writing configs, 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.
+
+Rationale:
+- Ensures reproducibility and auditability.
+- Avoids shell escaping bugs and cross-platform inconsistencies.
+- Aligns with project reliability protocol.
+
+Violation handling:
+- If any prior step used "node -e", revert and redo using write_to_file or replace_in_file.
+
+**Cross-reference:** This rule is also summarized in **webapp.md** (MUST FOLLOW #1). Both apply.

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

@@ -0,0 +1,32 @@
+---
+description: A4D rule — build UI first, then business logic for web apps
+alwaysApply: true
+---
+
+# A4D Rule: UI First, Then Business Logic (Proceed Immediately After UI)
+
+When building or modifying a web application (or any feature within it):
+
+1. **Build the UI first**
+   - Implement layout, structure, and components (pages, forms, lists, navigation).
+   - Apply styling, theming, and design-system usage so the interface is visually complete and navigable.
+   - Use placeholder or mock data only where needed to render the UI; do not wire real APIs yet.
+
+2. **Proceed to API and business logic immediately after UI completion (same iteration)**
+   - As soon as the UI for a feature is visually complete and routable, begin wiring the data layer for that same feature in the same iteration.
+   - Add data fetching (GraphQL preferred per LDS rules, then UI API; avoid Apex REST for React), state management, and event handlers.
+   - Connect forms and actions to real APIs and backend behavior.
+   - Add validation, loading, and user-friendly error states.
+   - Keep the build green; fix TypeScript and ESLint issues as you wire logic.
+
+3. **Quality gates before marking the feature complete**
+   - Run `npm run lint` and ensure 0 errors (warnings acceptable if minor).
+   - Run `npm run build` and ensure it passes.
+   - Replace any remaining mock data relevant to the feature with real data paths or clearly marked TODOs if blocked.
+
+**Rationale:** A visible, stable UI gives a clear target, and immediately wiring the API and business logic in the same iteration ensures end‑to‑end functionality and avoids stale mock UIs. This also aligns with design-system guidance (invoke **webapplications-design-system**) and LDS data access rules.
+
+Notes:
+- Within LDS, prefer GraphQL for complex reads and mutations; fall back to standard UI API adapters when appropriate.
+- For React apps, do not implement or call Apex REST. If server-side logic is truly required and cannot be achieved via GraphQL/UI API, surface a limitation explicitly.
+- If a feature's UI spans multiple pages, wire business logic page-by-page as each page's UI stabilizes, rather than deferring all logic to the end.

package/dist/.a4drules/webapp.md

@@ -0,0 +1,75 @@
+# MUST FOLLOW
+
+0. **Always invoke the `local-expert` MCP** when dealing with web applications: call **`get_expert_knowledge`** with topic **`webapplications-design-system`** (for UI/design), and with **`webapplications`** when generating or structuring the app. Do not skip the design-system expert for any web app UI work.
+1. **No `node -e`.** This project forbids `node -e` for any operation (file edits, config, shell automation). Use `replace_in_file` or `write_to_file` only. See **webapp-no-node-e.md**.
+
+# React Development & Stability Rules
+
+## Terminal & Execution Strategy
+- **NEVER use `node -e`** for file manipulation, string replacement, or reading files. Forbidden. Use `replace_in_file` or `write_to_file` only. 
+- ALWAYS use `replace_in_file` or `write_to_file` for code changes.
+- IF you must parse JSON (like package.json), use `jq` if available. Otherwise, read the file and process it internally.
+- ALWAYS use `npm` or `yarn` commands directly rather than writing custom Node scripts to trigger them.
+
+## React & TypeScript Standards
+- Component Architecture: Prefer functional components with hooks.
+- File Naming: Use PascalCase for components (e.g., `Button.tsx`) and camelCase for hooks (e.g., `useAuth.ts`).
+- Imports: Use absolute paths (e.g., `@/components/...`) if the `tsconfig.json` or `vite.config.ts` supports it.
+- State: Default to `useState` for local state; avoid adding global state libraries unless requested.
+
+## Reliability Protocol
+- Before running any build or test command, check for the existence of `node_modules`. If missing, prompt to run `npm install`.
+- When searching for code, use `search_files` with regex rather than trying to `grep` or `awk` through the terminal.
+- If a command fails twice, STOP and report the exact error to the user rather than attempting a third "creative" bash one-liner.
+
+# General app generation guidance
+
+Your goal is to create a functioning app on Salesforce platform. Do not mock UIs, but use tools at your disposal, such as custom objects, graphql API, Apex controllers in order to achieve your goal.
+
+**Home page must be populated:** The home page (root route) must never be left as the default template. Always populate it with real content—e.g. landing content, banners, tiles, hero, navigation to main features—tailored to the app or use case. Make it visually pleasing and purposeful. Do not leave placeholder or "Welcome to..." default content.
+
+**Replace default boilerplate:** Always replace default scaffold content (e.g. "React App", "Vite + React", default page titles, placeholder headings in index.html or App.tsx) with **project- or app-specific** names and copy. Do not leave generic "React App" or template placeholders in the UI or document title.
+
+**Navigation menu and placeholder name/design (critical — often missed):** **Build the navigation into the app layout** (`appLayout.tsx`) so every page shares the same nav. Always edit the **navigation menu** in that layout file: replace default nav items and labels with app-specific links and names; do not leave template "Home"/"About" or placeholder links. Always replace the **placeholder app name** in header, nav brand, footer, and `<title>` with the actual app name, and update **placeholder design** (header/footer/shell) so it's not the template default. See **webapp-nav-and-placeholders.md**.
+
+**Frontend aesthetics (avoid AI slop):** Make creative, distinctive frontends that surprise and delight. Use distinctive typography (avoid Inter, Roboto, Arial, Space Grotesk as defaults), cohesive color with sharp accents (use CSS variables; avoid purple-on-white clichés), high-impact motion (e.g. staggered reveals), and atmosphere/depth in backgrounds. Do not converge on generic, cookie-cutter layouts. Follow **webapplications-design-system** expert knowledge for full guidance.
+
+# SFDX React Web Application Creation
+
+When the user asks to **create a React app** (or a web app, webpplication, etc) in this SFDX project:
+
+1. **Generate the app** using the Salesforce CLI:
+   \`\`\`bash
+   sf webapp generate -n MyWebApp -t reactbasic
+   \`\`\`
+   Use the app name the user requested instead of \`MyWebApp\` if they specify one.
+
+Do not use \`create-react-app\`, Vite, or other generic React scaffolds for this scenario; use \`sf webapp generate\` so the app is SFDX-aware.
+
+2. **For B2B/B2C or authenticated/guest apps:** Also create site container metadata and create and configure Digital Experience Sites to host the React web application.
+
+When modifying webapp in an SFDX project, use the experts MCP to obtain the latest guidance and design before starting implementation. Never assume or create tools that are not explicitly available
+
+3. Repeat iterations until the there are no pending actions left.
+
+
+# Software development cycle (modified for continuous execution)
+
+- Execute tasks continuously until all planned items are complete in the current iteration, without pausing after intermediate checkpoints.
+- Maintain a running checklist and proceed through it sequentially.
+- Quality gates (lint/build) remain required, but failures should be remediated inline and the workflow should continue through all feature tasks in this iteration unless the user directs otherwise.
+
+## Attempt Completion Enforcement (Local Project Rule)
+
+- Do NOT invoke attempt_completion until ALL checklist items for the current iteration are complete and quality gates pass.
+- Intermediate status updates must use task_progress on tool calls (never attempt_completion) until completion criteria are met.
+- The only exceptions that allow early attempt_completion are:
+  - A blocking error that cannot be resolved after reasonable remediation and requires user input
+  - The user explicitly instructs to pause or complete early
+
+## Stop Conditions
+
+Only stop when:
+- All checklist items are completed and quality gates pass, or
+- A blocking error cannot be resolved after reasonable remediation, or
+- The user explicitly asks to pause.

package/dist/AGENT.md

@@ -0,0 +1,75 @@
+# Agent guide: SFDX project with React web app
+
+This project is a **Salesforce DX (SFDX) project** containing a **React web application**. The structure is generated; the app lives under `force-app/main/default/webapplications/<appName>/`. Use this file when working in this directory.
+
+## Project layout
+
+- **Project root**: this directory — SFDX project root. Contains `sfdx-project.json`, `force-app/`, and (optionally) LWC/Aura.
+- **React web app**: `force-app/main/default/webapplications/<appName>/`  
+  - Replace `<appName>` with the actual app folder name (e.g. `base-react-app`, or the name chosen when the app was generated).
+  - Entry: `src/App.tsx`  
+  - Routes: `src/routes.tsx`  
+  - API/GraphQL: `src/api/` (e.g. `graphql.ts`, `graphql-operations-types.ts`, `utils/`)
+
+Path convention: **webapplications** (lowercase).
+
+## Two package.json contexts
+
+### 1. Project root (this directory)
+
+Used for SFDX metadata (LWC, Aura, etc.). Scripts here are for the base SFDX template:
+
+| Command | Purpose |
+|---------|---------|
+| `npm run lint` | ESLint for `aura/` and `lwc/` |
+| `npm run test` | LWC Jest (passWithNoTests) |
+| `npm run prettier` | Format supported metadata files |
+| `npm run prettier:verify` | Check Prettier |
+
+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)
+
+**Always `cd` into the web app directory for dev/build/lint/test:**
+
+```bash
+cd force-app/main/default/webapplications/<appName>
+```
+
+| Command | Purpose |
+|---------|---------|
+| `npm run start` | Start Vite dev server |
+| `npm run build` | TypeScript (`tsc -b`) + Vite build |
+| `npm run lint` | ESLint for the React app |
+| `npm run test` | Vitest |
+| `npm run preview` | Preview production build |
+| `npm run graphql:codegen` | Generate GraphQL types |
+| `npm run graphql:schema` | Fetch GraphQL schema |
+
+**Before finishing changes:** run `npm run build` and `npm run lint` from the web app directory; both must succeed.
+
+## Agent rules (.a4drules)
+
+This project includes **.a4drules/** at the project root. Follow them when generating or editing code.
+
+When rules refer to “web app directory” or `force-app/main/default/webapplications/<appName>/`, use the **actual app folder name** for this project.
+
+## Deploying
+
+From **this project root**:
+
+```bash
+# Build the React app first (replace <appName> with the app folder name)
+cd force-app/main/default/webapplications/<appName> && npm i && npm run build && cd -
+
+# Deploy web app only
+sf project deploy start --source-dir force-app/main/default/webapplications --target-org <alias>
+
+# Deploy all metadata
+sf project deploy start --source-dir force-app --target-org <alias>
+```
+
+## Conventions (quick reference)
+
+- **UI**: shadcn/ui + Tailwind. Import from `@/components/ui/...`.
+- **Entry**: Keep `App.tsx` and routes in `src/`; add features as new routes or sections, don’t replace the app shell but you may modify it to match the requested design.

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.48.2](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.48.1...v1.48.2) (2026-02-23)
+
+**Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental
+
+
+
+
+
+## [1.48.1](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.48.0...v1.48.1) (2026-02-21)
+
+**Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental
+
+
+
+
+
 # [1.48.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.47.0...v1.48.0) (2026-02-20)
 
 **Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental

package/dist/force-app/main/default/webapplications/feature-react-chart/package-lock.json

@@ -6575,24 +6575,24 @@
       }
     },
     "node_modules/@ts-morph/common/node_modules/balanced-match": {
-      "version": "4.0.3",
-      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.3.tgz",
-      "integrity": "sha512-1pHv8LX9CpKut1Zp4EXey7Z8OfH11ONNH6Dhi2WDUt31VVZFXZzKwXcysBgqSumFCmR+0dqjMK5v5JiFHzi0+g==",
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz",
+      "integrity": "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==",
       "license": "MIT",
       "engines": {
-        "node": "20 || >=22"
+        "node": "18 || 20 || >=22"
       }
     },
     "node_modules/@ts-morph/common/node_modules/brace-expansion": {
-      "version": "5.0.2",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.2.tgz",
-      "integrity": "sha512-Pdk8c9poy+YhOgVWw1JNN22/HcivgKWwpxKq04M/jTmHyCZn12WPJebZxdjSa5TmBqISrUSgNYU3eRORljfCCw==",
+      "version": "5.0.3",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.3.tgz",
+      "integrity": "sha512-fy6KJm2RawA5RcHkLa1z/ScpBeA762UF9KmZQxwIbDtRJrgLzM10depAiEQ+CXYcoiqW1/m96OAAoke2nE9EeA==",
       "license": "MIT",
       "dependencies": {
         "balanced-match": "^4.0.2"
       },
       "engines": {
-        "node": "20 || >=22"
+        "node": "18 || 20 || >=22"
       }
     },
     "node_modules/@ts-morph/common/node_modules/minimatch": {
@@ -11573,9 +11573,9 @@
       }
     },
     "node_modules/hono": {
-      "version": "4.12.0",
-      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.0.tgz",
-      "integrity": "sha512-NekXntS5M94pUfiVZ8oXXK/kkri+5WpX2/Ik+LVsl+uvw+soj4roXIsPqO+XsWrAw20mOzaXOZf3Q7PfB9A/IA==",
+      "version": "4.12.1",
+      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.1.tgz",
+      "integrity": "sha512-hi9afu8g0lfJVLolxElAZGANCTTl6bewIdsRNhaywfP9K8BPf++F2z6OLrYGIinUwpRKzbZHMhPwvc0ZEpAwGw==",
       "license": "MIT",
       "engines": {
         "node": ">=16.9.0"

package/dist/force-app/main/default/webapplications/feature-react-chart/package.json

@@ -4,7 +4,7 @@
   "version": "1.0.0",
   "type": "module",
   "scripts": {
-    "dev": "vite",
+    "start": "vite",
     "build": "tsc -b && vite build",
     "build:e2e": "npm run build && node scripts/rewrite-e2e-assets.mjs",
     "lint": "eslint .",

package/dist/package.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/webapp-template-feature-react-chart-experimental",
-  "version": "1.48.0",
+  "version": "1.48.2",
   "description": "Chart feature with analytics chart components, agent skills, and rules (Recharts)",
   "license": "SEE LICENSE IN LICENSE.txt",
   "author": "",
@@ -27,7 +27,7 @@
     "clean": "rm -rf dist"
   },
   "devDependencies": {
-    "@salesforce/webapp-experimental": "^1.48.0",
+    "@salesforce/webapp-experimental": "^1.48.2",
     "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
     "react-dom": "^19.2.1",
@@ -46,10 +46,10 @@
       "build:dist-app": {
         "executor": "@salesforce/webapp-template-cli-experimental:build-dist-app"
       },
-      "dev": {
+      "start": {
         "executor": "@salesforce/webapp-template-cli-experimental:dev-server"
       }
     }
   },
-  "gitHead": "5ccfffec66505f70bdf4e6679e886c7bdabfe0ff"
+  "gitHead": "0b08119c77a0bac17a705ba303a89e4630a9b39f"
 }

package/dist/.a4drules/skills/install-feature/SKILL.md

@@ -1,66 +0,0 @@
----
-name: install-feature
-description: Install a feature into the current app. Use when the user asks to add a feature, capability, or functionality like authentication, search, charts, or navigation to their React web app. Do this when user wants to do _anything_ to webapplications/webapps.
----
-
-# Install feature
-
-When the user asks to add a feature to their app, follow this workflow.
-
-## 1. Match the request to a feature
-
-Available features (npm packages):
-
-
-| Feature                | Package                                                                 | Description                                                            |
-| ---------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| **Authentication**     | `@salesforce/webapp-template-feature-react-authentication-experimental` | Login, register, password reset, protected routes                      |
-| **Global search**      | `@salesforce/webapp-template-feature-react-global-search-experimental`  | Search Salesforce objects with filters and pagination                  |
-| **Analytics charts**   | `@salesforce/webapp-template-feature-react-chart-experimental`          | Recharts line/bar charts with theming (AnalyticsChart, ChartContainer) |
-| **GraphQL data access**| `@salesforce/webapp-template-feature-graphql-experimental`              | AI agent skills, rules, and docs for GraphQL development               |
-| **Shared UI (shadcn)** | `@salesforce/webapp-template-feature-react-shadcn-experimental`         | Button, Card, Input, Select, Table, Tabs, etc.                         |
-| **Micro frontends**    | `@salesforce/webapp-template-feature-micro-frontend-experimental` | Embed an App into Salesforce UI
-
-
-
-If no feature matches, tell the user and offer to build it from scratch following the project's existing patterns.
-
-## 2. Install the npm package
-
-```bash
-npm install <package-name>
-```
-
-## 3. Copy skills and rules from the package
-
-Run the script so skills and rules from the package are copied into your project. Pass `[skills-dir]` and `[rules-dir]` for your environment; the script reports what it copied.
-
-```bash
-# Default (e.g. Cline): .cline/skills, .clinerules
-bash <this-skill>/scripts/copy-feature-assets.sh <package-name>
-
-# Agentforce: .a4drules/ ([docs](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/devagent-rules.html))
-bash <this-skill>/scripts/copy-feature-assets.sh <package-name> .a4drules/skills .a4drules
-
-# Cursor: .cursor/skills, .cursor/rules
-bash <this-skill>/scripts/copy-feature-assets.sh <package-name> .cursor/skills .cursor/rules
-```
-
-## 4. Read the feature's exports and components
-
-Read the package's entry point (usually `index.ts` or the `main` field in its `package.json`) to understand what components and types it exports.
-
-Also read the `feature.ts` file if it exists — it lists dependencies on other features (e.g. shadcn) and any npm dependencies the feature needs (e.g. `recharts`). Install any missing dependencies.
-
-## 5. Implement the feature in the current app
-
-- **If the package exports reusable components** (e.g. `AnalyticsChart`, `ChartContainer`): import and use them directly. Follow the package's README or skill instructions for props, data shapes, and usage patterns.
-- **If the package is a reference implementation** (e.g. authentication pages, search pages): read its source code under `src/` as a reference, then create equivalent pages/components in the current app following the app's existing patterns and conventions.
-
-Place new routes inside the existing app's router (e.g. `routes.tsx`). Do not replace the app shell; add the feature as new routes or sections within it.
-
-## 6. Verify
-
-- Confirm the app builds without errors.
-- Confirm any new routes are accessible and render correctly.
-

package/dist/.a4drules/skills/install-feature/scripts/copy-feature-assets.sh

@@ -1,36 +0,0 @@
-#!/usr/bin/env bash
-# Copies skills/ and rules/ from an installed npm package into the current project.
-# Usage: bash <this-script> <package-name> [skills-dir] [rules-dir]
-#
-# Examples:
-#   bash copy-feature-assets.sh @salesforce/webapp-template-feature-graphql-experimental
-#   bash copy-feature-assets.sh @salesforce/webapp-template-feature-graphql-experimental .cursor/skills .cursor/rules
-set -euo pipefail
-
-PKG="${1:?Usage: copy-feature-assets.sh <package-name> [skills-dir] [rules-dir]}"
-SKILLS_DIR="${2:-.cline/skills}"
-RULES_DIR="${3:-.clinerules}"
-
-PKG_DIR="node_modules/$PKG"
-
-if [ ! -d "$PKG_DIR" ]; then
-  echo "Error: Package not found at $PKG_DIR" >&2
-  echo "Run 'npm install $PKG' first." >&2
-  exit 1
-fi
-
-if [ -d "$PKG_DIR/skills" ] && [ "$(ls -A "$PKG_DIR/skills")" ]; then
-  mkdir -p "$SKILLS_DIR"
-  cp -r "$PKG_DIR"/skills/* "$SKILLS_DIR"/
-  echo "Copied skills → $SKILLS_DIR/"
-else
-  echo "No skills/ found in $PKG_DIR — nothing to copy."
-fi
-
-if [ -d "$PKG_DIR/rules" ] && [ "$(ls -A "$PKG_DIR/rules")" ]; then
-  mkdir -p "$RULES_DIR"
-  cp -r "$PKG_DIR"/rules/* "$RULES_DIR"/
-  echo "Copied rules  → $RULES_DIR/"
-else
-  echo "No rules/ found in $PKG_DIR — nothing to copy."
-fi