[chintandesai-cimulate]

Description

Make AI-assisted storefront search configurable globally or per site, with product-first results, streamed overviews, grounded follow-ups, and Commerce Agent context handoff. All sites default to the existing search experience. Overview copy presents highlighted products as examples and invites shoppers to browse the full results below, without announcing a fixed number of options.

Use Business Manager as the ECA credential owner. LLM_GATEWAY_AUTH_MODE=eca now selects a server-only consumer of an ECOM token broker. PWA authenticates as a dedicated Account Manager machine client and receives only a short-lived Gateway JWT; the ECA client ID, secret, and My Domain remain in BM. The working api_key path remains the default. Local ECA secrets require the explicit eca_direct development mode.

Required platform dependency: this PR implements the PWA consumer and documents the companion ECOM broker contract. The proposed native endpoint and sfcc.llm-auth scope are not currently shipped capabilities and are not implemented by this PR. They must be implemented/deployed and authorized before BM-backed ECA can be enabled. Cartridge scripts cannot access the internal BM credential, and no credential-export or shopper-accessible token route is introduced.

Types of Changes

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Documentation update
• Breaking change
• Other changes

Changes

• Add app.searchSummary defaults and app.sites[].searchSummary overrides for enablement, header search, homepage hero/copy/artwork, follow-ups, and agent handoff. Enforce site flags server-side before paid work; feature-off startup requires no Gateway credentials.
• Add PWA search/follow-up/handoff controllers, separate prompts, catalog grounding, real product picks, and result-derived suggestions. Preserve one shopper session while limiting visible/model/handoff history to the current query, filters, site, locale, currency, and sort.
• Set explicit dark text and white backgrounds on hero/header AI search inputs so the hero’s white text does not make typed queries invisible.
• Refresh suggested shopper questions after every successful overview/follow-up from the latest answer, current catalog context, preferences and search-scoped history. Show the active questions below the conversation and hide stale chips while answering. Question generation is one additional completed Gateway call per answered turn when follow-ups are enabled, with a five-second deadline and 256 requested tokens on the API-key profile; failure retains the answer with validated catalog fallbacks. Streamed answer text is delivered before this metadata step.
• Generalize the overview introduction and grounding scope. Keep highlighted cards while directing shoppers to all matching products below.
• Render Markdown in the streamed overview and follow-up answers, including lists, emphasis, headings, links, quotes, code, and tables. Disable raw HTML and unsafe URLs, keep model-authored remote images inert, and preserve original Markdown in conversation history. Vendor the pinned parser and its license without changing package dependencies.
• Initialize Commerce Client page context, transfer current-search history, queue the query until connected, and avoid duplicate sends. Support per-site agent settings and reuse upstream's existing embedded PDP assistant.
• Separate API-key, BM-backed ECA, and direct-ECA adapters. The BM client pins destinations, derives AM tenant scope from the configured broker URL, validates JWT lifetime/tenant metadata, shares refreshes, handles bounded authentication retries, and never falls back to another identity. A shopper disconnect cannot cancel a refresh needed by another shopper.
• Keep AM credentials confined to server configuration; send no ECA secret, shopper token, prompt, or selectable credential ID to the broker. Preserve direct Gateway streaming from PWA after authentication.
• Add an architecture walkthrough with six Mermaid diagrams covering components, product-first SSE, follow-up decisions, search-scoped history, agent handoff and auth modes, plus the differences from SFRA. All diagrams parse and local source links resolve.
• Document the required native ECOM endpoint, service-client authorization, response contract, and rollout gate in packages/template-retail-react-app/docs/BM-ECA-TOKEN-BROKER.md. Setup examples remain in docs/README-SEARCH-SUMMARY.md.
• Remove customer deployment assumptions and implicit sibling widget builds. Lazy-load optional UI/handoff chunks. Increase the main bundle budget from 111 kB to 112 kB for shared feature/session helpers; retain the vendor budget.

Preview limits

BM-backed ECA cannot be enabled until the companion ECOM API and scope are available and live-tested. No live BM credential exchange is claimed by the mocked provider tests. Direct ECA is also not live-enabled in this draft.

Conversation/result storage and concurrency limits remain process-local. Shared TTL storage, distributed quotas/abuse controls, and streaming validation are required before scaled MRT rollout. Current custom endpoints use bearer-token shopper mode; HttpOnly-cookie stores need a cookie-aware adapter. Upstream ECA output limits, widget cold starts, accessibility, and translations require rollout validation.

How to Test-Drive This PR

1. Leave the flags off and confirm existing search/home/header behavior without Gateway credentials.
2. Enable site A with searchSummary.enabled: true while site B stays disabled. Optionally configure site-specific hero copy/artwork/suggestions; verify disabled-site endpoints are rejected before paid work.
3. Use the existing API-key server settings to search, see products before streamed text, and ask a result-specific follow-up. Overviews should describe selected highlights generally and direct shoppers to the full results below. Changing search keeps the shopper session while excluding unrelated history.
4. Configure a compatible Commerce Client and enable agentHandoff to verify context plus a single automatically queued query. Configure the existing app.embeddedAgent settings separately for PDP questions.
5. For BM-backed ECA, first deploy the native ECOM broker from the companion contract and provision its restricted AM client. Set LLM_GATEWAY_AUTH_MODE=eca, LLM_GATEWAY_BM_TOKEN_URL, LLM_GATEWAY_BM_AM_CLIENT_ID, and LLM_GATEWAY_BM_AM_CLIENT_SECRET. Keep the ECA credentials only in BM. Missing broker configuration fails closed; API key remains a separate explicit mode.
6. For direct-ECA development only, select eca_direct and supply the existing direct ECA environment settings.

Validation:

• 21-suite focused regression: 365 passed, 1 skipped. Authentication suites passed 40 tests; after the wording change the three affected summary suites passed 35 tests.
• One live Gateway generation confirmed no fixed option count and an invitation to browse the results below; prompts and generated text were not logged. The local NTO demo was restarted with its existing configuration and responded with HTTP 200.
• ESLint and Prettier on changed source; git diff --check.
• Production webpack build and gzip budgets pass: main.js 114,491 / 114,688 bytes; vendor.js 415,237 / 421,888 bytes.
• Markdown follow-up regression: 114 tests / 11 suites passed; the final renderer/summary run passed 14 tests / 2 suites. Live local browser checks confirm semantic bold/list elements from streamed output. Production build, changed-source lint/formatting, and diff checks pass.
• Conversation-aware question regression: 95 tests / 8 suites passed, including Gateway/BM auth, consecutive turns, latest-answer grounding, search isolation, malformed/duplicate metadata, timeout/cancellation, UI placement and the real request token cap. Live NTO checks show fresh questions after an overview and two consecutive follow-ups. Production build and existing gzip budgets pass; architecture diagrams are revalidated.
• Input contrast regression: 10 tests / 2 suites passed. Browser-computed styles confirm dark text on white for both fields; production build and gzip budgets still pass.
• Gateway/BM credential variables are absent from browser chunks. No credential files or customer deployment settings are included.
• The available private-client E2E CI run failed in Configure AWS Credentials, before tests. A live BM/ECOM integration and accessibility validation remain outstanding.

Checklists

General

• Changes are covered by test cases
• CHANGELOG.md updated

Accessibility Compliance

• There are no changes to UI
• Changes were tested with a Screen Reader (iOS VoiceOver or Android Talkback) and had no issues
• Changes comply with WCAG 2.0 levels A and AA
• Changes to common UI patterns and interactions comply with WAI-ARIA best practices

Localization

• Changes include a UI text update in the Retail React App (which requires translation)

[git2gus]

Git2Gus App is installed but the .git2gus/config.json doesn't have right values. You should add the required configuration.

[cc-prodsec]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.