@gengage/assistant-fe 0.3.21 → 0.3.23

package/README.md

@@ -4,7 +4,7 @@
 [![tests](https://img.shields.io/badge/tests-passing-brightgreen)]()
 [![license](https://img.shields.io/badge/license-source--available-blue)](LICENSE)
 
-Embeddable AI shopping assistant widgets for e-commerce — **chat**, **contextual Q&A**, and **similar products** — built with vanilla TypeScript, zero framework dependencies.
+Embeddable AI shopping assistant widgets for e-commerce — **chat**, **contextual Q&A**, **similar products**, and an optional **find-similar PDP image overlay** — built with vanilla TypeScript, zero framework dependencies.
 
 > Backend services require a [gengage.ai](https://gengage.ai) subscription.
 > See [LEGAL.md](./LEGAL.md) and [TRADEMARKS.md](./TRADEMARKS.md).
@@ -16,10 +16,10 @@ Embeddable AI shopping assistant widgets for e-commerce — **chat**, **contextu
 ### CDN Script Tag (fastest)
 
 ```html
-<script src="https://unpkg.com/@gengage/assistant-fe/dist/gengage-assistant.iife.js"></script>
+<script src="https://unpkg.com/@gengage/assistant-fe/dist/chat.iife.js"></script>
 <script>
-  GengageAssistant.initFromConfig({
-    version: '1',
+  const chat = new window.Gengage.GengageChat();
+  chat.init({
     accountId: 'YOUR_ACCOUNT_ID',
     middlewareUrl: 'https://YOUR_BACKEND_URL',
   });
@@ -57,6 +57,7 @@ await chat.init({
     chat: { variant: 'floating' },
     qna: { mountTarget: '#qna-section' },
     simrel: { mountTarget: '#similar-products' },
+    simbut: { mountTarget: '#product-gallery' },
   });
 </script>
 ```
@@ -87,6 +88,7 @@ See [docs/native-mobile-sdk.md](docs/native-mobile-sdk.md) for iOS WKWebView, An
 | **Chat** | `@gengage/assistant-fe/chat` | Floating AI drawer with streaming responses, product cards, comparison tables |
 | **QNA** | `@gengage/assistant-fe/qna` | Contextual action buttons for product pages |
 | **SimRel** | `@gengage/assistant-fe/simrel` | AI-powered similar/related product grid |
+| **SimBut** | `@gengage/assistant-fe/simbut` | PDP image-overlay pill that opens a `findSimilar` flow for the current product |
 | **Native** | `@gengage/assistant-fe/native` | Android/iOS WebView bridge + overlay bootstrap |
 
 ---
@@ -102,9 +104,11 @@ chat.init({
 
 **Component overrides** — swap any UI component via the json-render registry.
 
+**SimBut customization** — use theme tokens, `i18n.findSimilarLabel`, and `onFindSimilar` for the PDP image-overlay pill.
+
 **Full fork** — replace `src/chat/components/` entirely; keep `catalog.ts` + `index.ts`.
 
-See [CUSTOMIZATION-GUIDE.md](CUSTOMIZATION-GUIDE.md) for the full playbook.
+See [docs/customization.md](docs/customization.md) for the fork and merchant-customization playbook.
 
 ---
 
@@ -117,6 +121,7 @@ npm run typecheck                              # TypeScript strict check
 npm run test                                   # Unit tests
 npm run build                                  # Build to dist/
 npm run catalog                                # Visual component catalog at :3002
+npm run docs:build                             # Build contributor docs with VitePress
 ```
 
 **Using a local backend:**
@@ -137,14 +142,20 @@ MIDDLEWARE_URL=http://localhost:7860 npm run dev -- koctascomtr --sku=1000465056
 
 | Doc | Description |
 |-----|-------------|
+| [Docs Index](docs/index.md) | Full documentation map |
+| [API Reference](docs/api-reference.md) | Public entry points and config surfaces |
 | [Architecture](docs/architecture.md) | System design, widget lifecycle, data flows |
 | [Wire Protocol](docs/wire-protocol.md) | Backend NDJSON streaming contract |
 | [Customization](docs/customization.md) | CSS tokens, component overrides, XSS rules |
+| [i18n](docs/i18n.md) | Locale resolution and string overrides |
+| [Error Handling](docs/error-handling.md) | Offline, retry, and recovery behavior |
 | [GTM Quickstart](docs/gtm-quickstart.md) | Copy-paste GTM embedding patterns |
 | [Security](docs/security-production.md) | Production CSP, postMessage origins, sanitization |
 | [Analytics](docs/analytics-contract.md) | Event taxonomy and attribution |
 | [Mobile SDK](docs/native-mobile-sdk.md) | Android/iOS/React Native integration |
 | [New Account](docs/new-account-guide.md) | Adding a new merchant demo |
+| [AGENTS](AGENTS.md) | Coding-agent architecture and code-path index |
+| [Contributing](CONTRIBUTING.md) | Shared SDK contribution workflow |
 
 ---
 
@@ -156,8 +167,9 @@ src/
   chat/       # Chat widget (GengageChat class + components)
   qna/        # QNA widget (GengageQNA class + components)
   simrel/     # Similar products widget (GengageSimRel class + components)
+  simbut/     # PDP image overlay pill widget (GengageSimBut class)
   native/     # Native WebView bridge exports
-demos/        # 12 merchant-branded demo pages
+demos/        # Merchant-branded demo pages and framework integration examples
 catalog/      # Visual component catalog (mock data, no backend)
 docs/         # Architecture, wire protocol, customization, analytics
 tests/        # Vitest unit tests + Playwright E2E

package/dist/chat/catalog.d.ts

@@ -362,6 +362,11 @@ export declare const HandoffNoticeSchema: z.ZodObject<{
 export declare const PhotoAnalysisCardSchema: z.ZodObject<{
     summary: z.ZodString;
     clues: z.ZodArray<z.ZodString>;
+    strengths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    focus_points: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    celeb_style: z.ZodOptional<z.ZodString>;
+    celeb_style_reason: z.ZodOptional<z.ZodString>;
+    details: z.ZodOptional<z.ZodArray<z.ZodString>>;
     next_question: z.ZodOptional<z.ZodString>;
     style_images: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
@@ -758,10 +763,15 @@ export declare const chatCatalog: {
             readonly schema: z.ZodObject<{
                 summary: z.ZodString;
                 clues: z.ZodArray<z.ZodString>;
+                strengths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                focus_points: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                celeb_style: z.ZodOptional<z.ZodString>;
+                celeb_style_reason: z.ZodOptional<z.ZodString>;
+                details: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 next_question: z.ZodOptional<z.ZodString>;
                 style_images: z.ZodOptional<z.ZodArray<z.ZodString>>;
             }, z.core.$strip>;
-            readonly description: "Structured photo analysis card with summary, clues, and follow-up question.";
+            readonly description: "Structured photo analysis card with strengths, focus points, celeb vibe, details, and follow-up question.";
         };
         readonly BeautyPhotoStep: {
             readonly schema: z.ZodObject<{

package/dist/chat/components/ChatDrawer.d.ts

@@ -303,6 +303,11 @@ export declare class ChatDrawer {
     updateBotMessage(messageId: string, html: string, renderHint?: string, photoAnalysis?: {
         summary: string;
         clues: string[];
+        strengths?: string[];
+        focusPoints?: string[];
+        celebStyle?: string;
+        celebStyleReason?: string;
+        details?: string[];
         nextQuestion?: string;
     }): void;
     /** Mark a message as the first bot message in its thread (for special styling). */

package/dist/chat/components/PhotoAnalysisCard.d.ts

@@ -3,6 +3,11 @@ import { ChatUISpecRenderContext } from '../types.js';
 export interface PhotoAnalysisData {
     summary: string;
     clues: string[];
+    strengths?: string[];
+    focusPoints?: string[];
+    celebStyle?: string;
+    celebStyleReason?: string;
+    details?: string[];
     nextQuestion?: string;
 }
 /** Extract structured photo-analysis data from a UISpec element's props. */
@@ -12,11 +17,13 @@ export declare function renderPhotoAnalysisCard(element: UIElement, ctx: ChatUIS
  * Renders a photo analysis card into a chat message bubble.
  *
  * When structured data is available (from a PhotoAnalysisCard UISpec), it renders
- * the summary, clues, and next question directly. Otherwise, falls back to a
- * sentence-splitting heuristic for old backends that don't send the UISpec.
+ * the summary, sections, and follow-up question directly. Otherwise, falls back
+ * to a sentence-splitting heuristic for old backends that don't send the UISpec.
  */
-export declare function renderPhotoAnalysisBubble(container: HTMLElement, content: string, badgeText: string, structured?: {
-    summary: string;
-    clues: string[];
-    nextQuestion?: string;
-}): void;
+export declare function renderPhotoAnalysisBubble(container: HTMLElement, content: string, labels: {
+    badge: string;
+    strengths: string;
+    focus: string;
+    celebStyle: string;
+    seeMore: string;
+}, structured?: PhotoAnalysisData): void;

package/dist/chat/types.d.ts

@@ -258,6 +258,14 @@ export interface ChatI18n {
     aiBrowseCategoriesTitle: string;
     /** Badge text on photo analysis message cards. */
     photoAnalysisBadge: string;
+    /** Photo analysis section label: strengths. */
+    photoAnalysisStrengthsLabel: string;
+    /** Photo analysis section label: focus points. */
+    photoAnalysisFocusLabel: string;
+    /** Photo analysis section label: celeb style match. */
+    photoAnalysisCelebStyleLabel: string;
+    /** Photo analysis expander summary text. */
+    photoAnalysisSeeMoreLabel: string;
     /** Beauty photo step card: title. */
     beautyPhotoStepTitle: string;
     /** Beauty photo step card: description. */
@@ -323,7 +331,7 @@ export interface ChatUISpecRenderContext {
     onProductSelect?: (product: Record<string, unknown>) => void;
     pricing?: import('../common/price-formatter.js').PriceFormatConfig | undefined;
     productPriceUi?: ProductPriceUiConfig | undefined;
-    i18n?: Pick<ChatI18n, 'productCtaLabel' | 'viewOnSiteLabel' | 'aiTopPicksTitle' | 'roleWinner' | 'roleBestValue' | 'roleBestAlternative' | 'viewDetails' | 'groundingReviewCta' | 'groundingReviewSubtitle' | 'variantsLabel' | 'sortRelated' | 'sortPriceAsc' | 'sortPriceDesc' | 'sortToolbarAriaLabel' | 'compareSelected' | 'compareMinHint' | 'comparisonSelectLabel' | 'comparisonSelectedLabel' | 'comparisonSelectCardHint' | 'panelTitleProductDetails' | 'panelTitleSimilarProducts' | 'panelTitleComparisonResults' | 'panelTitleCategories' | 'panelTitleSearchResults' | 'inStockLabel' | 'outOfStockLabel' | 'findSimilarLabel' | 'galleryPrevAriaLabel' | 'galleryNextAriaLabel' | 'beautyStylesPreparedTitle' | 'watchStylesPreparedTitle' | 'viewMoreLabel' | 'similarProductsLabel' | 'addToCartButton' | 'shareButton' | 'productInfoTab' | 'specificationsTab' | 'recommendedChoiceLabel' | 'highlightsLabel' | 'keyDifferencesLabel' | 'specialCasesLabel' | 'emptyReviewsMessage' | 'closeAriaLabel' | 'dismissAriaLabel' | 'startChatLabel' | 'handoffHeading' | 'customerReviewsTitle' | 'addToFavoritesLabel' | 'reviewFilterPositive' | 'reviewFilterNegative' | 'decreaseLabel' | 'increaseLabel' | 'reviewCustomersMentionSingular' | 'reviewCustomersMentionPlural' | 'reviewSubjectsHeading' | 'aiBrowseCategoriesTitle' | 'photoAnalysisBadge' | 'beautyPhotoStepTitle' | 'beautyPhotoStepDescription' | 'beautyPhotoStepUpload' | 'beautyPhotoStepProcessing' | 'beautyPhotoStepSkip'>;
+    i18n?: Pick<ChatI18n, 'productCtaLabel' | 'viewOnSiteLabel' | 'aiTopPicksTitle' | 'roleWinner' | 'roleBestValue' | 'roleBestAlternative' | 'viewDetails' | 'groundingReviewCta' | 'groundingReviewSubtitle' | 'variantsLabel' | 'sortRelated' | 'sortPriceAsc' | 'sortPriceDesc' | 'sortToolbarAriaLabel' | 'compareSelected' | 'compareMinHint' | 'comparisonSelectLabel' | 'comparisonSelectedLabel' | 'comparisonSelectCardHint' | 'panelTitleProductDetails' | 'panelTitleSimilarProducts' | 'panelTitleComparisonResults' | 'panelTitleCategories' | 'panelTitleSearchResults' | 'inStockLabel' | 'outOfStockLabel' | 'findSimilarLabel' | 'galleryPrevAriaLabel' | 'galleryNextAriaLabel' | 'beautyStylesPreparedTitle' | 'watchStylesPreparedTitle' | 'viewMoreLabel' | 'similarProductsLabel' | 'addToCartButton' | 'shareButton' | 'productInfoTab' | 'specificationsTab' | 'recommendedChoiceLabel' | 'highlightsLabel' | 'keyDifferencesLabel' | 'specialCasesLabel' | 'emptyReviewsMessage' | 'closeAriaLabel' | 'dismissAriaLabel' | 'startChatLabel' | 'handoffHeading' | 'customerReviewsTitle' | 'addToFavoritesLabel' | 'reviewFilterPositive' | 'reviewFilterNegative' | 'decreaseLabel' | 'increaseLabel' | 'reviewCustomersMentionSingular' | 'reviewCustomersMentionPlural' | 'reviewSubjectsHeading' | 'aiBrowseCategoriesTitle' | 'photoAnalysisBadge' | 'photoAnalysisStrengthsLabel' | 'photoAnalysisFocusLabel' | 'photoAnalysisCelebStyleLabel' | 'photoAnalysisSeeMoreLabel' | 'beautyPhotoStepTitle' | 'beautyPhotoStepDescription' | 'beautyPhotoStepUpload' | 'beautyPhotoStepProcessing' | 'beautyPhotoStepSkip'>;
     productSort?: ProductSortState | undefined;
     onSortChange?: ((sort: ProductSortState) => void) | undefined;
     comparisonSelectMode?: boolean | undefined;
@@ -367,6 +375,11 @@ export interface ChatMessage {
     photoAnalysis?: {
         summary: string;
         clues: string[];
+        strengths?: string[];
+        focusPoints?: string[];
+        celebStyle?: string;
+        celebStyleReason?: string;
+        details?: string[];
         nextQuestion?: string;
     };
     timestamp: number;