@gengage/assistant-fe 0.5.7 → 0.6.0

package/dist/chat/api.d.ts

@@ -0,0 +1,17 @@
+import type { ChatTransportConfig } from '../common/api-paths.js';
+import type { ActionEnrichmentContext, ProcessActionRequest, StreamCallbacks } from '../common/transport.js';
+export type { ActionEnrichmentContext, BackendRequestMeta, InjectorAdapter, ProcessActionRequest, StreamCallbacks, } from '../common/transport.js';
+/**
+ * Enriches action payloads with fields the backend expects.
+ * Only adds fields that are not already present in the payload.
+ */
+export declare function enrichActionPayload(action: {
+    title: string;
+    type: string;
+    payload?: unknown;
+}, ctx: ActionEnrichmentContext): {
+    title: string;
+    type: string;
+    payload?: unknown;
+};
+export declare function sendChatMessage(request: ProcessActionRequest, callbacks: StreamCallbacks, transport: ChatTransportConfig): AbortController;

package/dist/chat/assistant-mode.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Assistant-mode utilities for the chat widget.
+ *
+ * The chat widget can operate in multiple modes (shopping, beauty consulting,
+ * and account expert). This module contains the type,
+ * parsing helpers, and recognised mode list so the main index.ts stays focused
+ * on orchestration.
+ */
+export type AssistantMode = 'shopping' | 'beauty_consulting' | 'account_expert';
+/** Return the value as an AssistantMode if it is a known mode string, otherwise null. */
+export declare function toAssistantMode(value: unknown): AssistantMode | null;
+/** Safely cast an unknown value to a plain Record, or null. */
+export declare function asRecord(value: unknown): Record<string, unknown> | null;
+/**
+ * Parse a redirect metadata payload and return the target assistant mode,
+ * or `null` if the payload is not a valid mode-switch redirect.
+ */
+export declare function parseRedirectMode(redirectPayload: unknown): AssistantMode | null;
+/** Resolve the process_action type for staged image/file attachments in a mode. */
+export declare function attachmentActionTypeForMode(mode: AssistantMode): 'user_message' | 'findSimilar';

package/dist/chat/attachment-utils.d.ts

@@ -0,0 +1,9 @@
+export declare const ALLOWED_MIME_TYPES: readonly ["image/jpeg", "image/png", "image/webp"];
+export declare const MAX_FILE_SIZE: number;
+export type ValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'invalid_type' | 'too_large';
+};
+export declare function validateImageFile(file: File): ValidationResult;

package/dist/chat/catalog.d.ts

@@ -0,0 +1,455 @@
+/**
+ * Chat widget — json-render catalog definition.
+ *
+ * This catalog describes all UI components the chat widget understands.
+ * The backend streams `ui_spec` events whose element types must match names
+ * defined here. Component implementations live in ./registry.tsx.
+ *
+ * HOW IT WORKS:
+ *   1. Backend streams NDJSON events including `ui_spec` events.
+ *   2. Each `ui_spec` event contains a `spec: UISpec` field.
+ *   3. The `<ChatRenderer>` component feeds specs into json-render's `<Renderer>`.
+ *   4. json-render looks up the element `type` in the registry and renders it.
+ *
+ * CUSTOMISING:
+ *   Fork this repo, edit ./registry.tsx to swap in your own components.
+ *   The catalog schema below stays the same — only the visual implementation changes.
+ *
+ * See: https://github.com/vercel-labs/json-render
+ */
+import { z } from 'zod';
+export declare const chatCatalog: {
+    readonly components: {
+        readonly MessageBubble: {
+            readonly schema: z.ZodObject<{
+                role: z.ZodEnum<{
+                    user: "user";
+                    assistant: "assistant";
+                }>;
+                content: z.ZodString;
+                timestamp: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>;
+            readonly description: "A single chat message bubble for user or assistant turns.";
+        };
+        readonly ProductCard: {
+            readonly schema: z.ZodObject<{
+                sku: z.ZodString;
+                name: z.ZodString;
+                imageUrl: z.ZodOptional<z.ZodString>;
+                price: z.ZodOptional<z.ZodString>;
+                originalPrice: z.ZodOptional<z.ZodString>;
+                url: z.ZodString;
+                ctaLabel: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>;
+            readonly description: "A product card rendered inline in the chat stream.";
+        };
+        readonly ActionButtons: {
+            readonly schema: z.ZodObject<{
+                buttons: z.ZodArray<z.ZodObject<{
+                    label: z.ZodString;
+                    action: z.ZodObject<{
+                        title: z.ZodString;
+                        type: z.ZodString;
+                        payload: z.ZodOptional<z.ZodUnknown>;
+                    }, z.core.$strip>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>;
+            readonly description: "A horizontal row of quick-reply action buttons.";
+        };
+        readonly TypingIndicator: {
+            readonly schema: z.ZodObject<{}, z.core.$strip>;
+            readonly description: "An animated indicator shown while the assistant is typing.";
+        };
+        readonly Divider: {
+            readonly schema: z.ZodObject<{
+                label: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>;
+            readonly description: "A horizontal rule with an optional label.";
+        };
+        readonly ComparisonTable: {
+            readonly schema: z.ZodObject<{
+                recommended: z.ZodObject<{
+                    sku: z.ZodString;
+                    name: z.ZodString;
+                    price: z.ZodString;
+                    url: z.ZodOptional<z.ZodString>;
+                    imageUrl: z.ZodOptional<z.ZodString>;
+                    rating: z.ZodOptional<z.ZodNumber>;
+                    reviewCount: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strip>;
+                products: z.ZodArray<z.ZodObject<{
+                    sku: z.ZodString;
+                    name: z.ZodString;
+                    price: z.ZodString;
+                    url: z.ZodOptional<z.ZodString>;
+                    imageUrl: z.ZodOptional<z.ZodString>;
+                    rating: z.ZodOptional<z.ZodNumber>;
+                    reviewCount: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strip>>;
+                attributes: z.ZodArray<z.ZodObject<{
+                    label: z.ZodString;
+                    values: z.ZodArray<z.ZodString>;
+                }, z.core.$strip>>;
+                highlights: z.ZodArray<z.ZodString>;
+                specialCases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                recommendedText: z.ZodOptional<z.ZodString>;
+                winnerHits: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                    positive: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    negative: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                }, z.core.$strip>>>;
+                productActions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                    title: z.ZodString;
+                    type: z.ZodString;
+                    payload: z.ZodOptional<z.ZodUnknown>;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>;
+            readonly description: "A product comparison table with recommended pick, attribute rows, and highlights.";
+        };
+        readonly AITopPicks: {
+            readonly schema: z.ZodObject<{
+                suggestions: z.ZodArray<z.ZodObject<{
+                    product: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                    role: z.ZodOptional<z.ZodString>;
+                    reason: z.ZodOptional<z.ZodString>;
+                    labels: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        label: z.ZodString;
+                        sentiment: z.ZodOptional<z.ZodEnum<{
+                            positive: "positive";
+                            negative: "negative";
+                            neutral: "neutral";
+                        }>>;
+                    }, z.core.$strip>>>;
+                    expertQualityScore: z.ZodOptional<z.ZodNumber>;
+                    reviewHighlight: z.ZodOptional<z.ZodString>;
+                    action: z.ZodOptional<z.ZodObject<{
+                        title: z.ZodString;
+                        type: z.ZodString;
+                        payload: z.ZodOptional<z.ZodUnknown>;
+                    }, z.core.$strip>>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>;
+            readonly description: "Rich AI-curated product suggestion cards with roles, sentiment labels, scores, and review quotes.";
+        };
+        readonly GroundingReviewCard: {
+            readonly schema: z.ZodObject<{
+                title: z.ZodOptional<z.ZodString>;
+                text: z.ZodOptional<z.ZodString>;
+                reviewCount: z.ZodOptional<z.ZodString>;
+                action: z.ZodObject<{
+                    title: z.ZodString;
+                    type: z.ZodString;
+                    payload: z.ZodOptional<z.ZodUnknown>;
+                }, z.core.$strip>;
+            }, z.core.$strip>;
+            readonly description: "A card showing review grounding data with review count and CTA.";
+        };
+        readonly AIGroupingCards: {
+            readonly schema: z.ZodObject<{
+                entries: z.ZodArray<z.ZodObject<{
+                    name: z.ZodString;
+                    image: z.ZodOptional<z.ZodString>;
+                    description: z.ZodOptional<z.ZodString>;
+                    action: z.ZodObject<{
+                        title: z.ZodString;
+                        type: z.ZodString;
+                        payload: z.ZodOptional<z.ZodUnknown>;
+                    }, z.core.$strip>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>;
+            readonly description: "Category grouping cards with images and labels for product discovery.";
+        };
+        readonly AISuggestedSearchCards: {
+            readonly schema: z.ZodObject<{
+                entries: z.ZodArray<z.ZodObject<{
+                    shortName: z.ZodString;
+                    detailedMessage: z.ZodOptional<z.ZodString>;
+                    whyDifferent: z.ZodOptional<z.ZodString>;
+                    image: z.ZodOptional<z.ZodString>;
+                    action: z.ZodObject<{
+                        title: z.ZodString;
+                        type: z.ZodString;
+                        payload: z.ZodOptional<z.ZodUnknown>;
+                    }, z.core.$strip>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>;
+            readonly description: "Suggested search cards with images, descriptions, and differentiation.";
+        };
+        readonly ProductDetailsPanel: {
+            readonly schema: z.ZodObject<{
+                product: z.ZodOptional<z.ZodObject<{
+                    sku: z.ZodOptional<z.ZodString>;
+                    name: z.ZodOptional<z.ZodString>;
+                    images: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    imageUrl: z.ZodOptional<z.ZodString>;
+                    rating: z.ZodOptional<z.ZodNumber>;
+                    reviewCount: z.ZodOptional<z.ZodNumber>;
+                    price: z.ZodOptional<z.ZodString>;
+                    originalPrice: z.ZodOptional<z.ZodString>;
+                    discountReason: z.ZodOptional<z.ZodString>;
+                    discount_reason: z.ZodOptional<z.ZodString>;
+                    campaignReason: z.ZodOptional<z.ZodString>;
+                    campaign_reason: z.ZodOptional<z.ZodString>;
+                    originalPriceStyle: z.ZodOptional<z.ZodEnum<{
+                        inline: "inline";
+                        strikethrough: "strikethrough";
+                    }>>;
+                    price_original_style: z.ZodOptional<z.ZodEnum<{
+                        inline: "inline";
+                        strikethrough: "strikethrough";
+                    }>>;
+                    price_discount_rate: z.ZodOptional<z.ZodNumber>;
+                    price_async: z.ZodOptional<z.ZodBoolean>;
+                    inStock: z.ZodOptional<z.ZodBoolean>;
+                    promotions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    variants: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        name: z.ZodOptional<z.ZodString>;
+                        value: z.ZodOptional<z.ZodString>;
+                        option_value: z.ZodOptional<z.ZodString>;
+                        attribute_value: z.ZodOptional<z.ZodString>;
+                        type: z.ZodOptional<z.ZodString>;
+                        attribute: z.ZodOptional<z.ZodString>;
+                        option_name: z.ZodOptional<z.ZodString>;
+                        attribute_name: z.ZodOptional<z.ZodString>;
+                        variant_name: z.ZodOptional<z.ZodString>;
+                        sku: z.ZodOptional<z.ZodString>;
+                        price: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+                        price_discounted: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+                        image: z.ZodOptional<z.ZodString>;
+                        imageUrl: z.ZodOptional<z.ZodString>;
+                        image_url: z.ZodOptional<z.ZodString>;
+                        color: z.ZodOptional<z.ZodString>;
+                        colour: z.ZodOptional<z.ZodString>;
+                        color_hex: z.ZodOptional<z.ZodString>;
+                        hex: z.ZodOptional<z.ZodString>;
+                        swatch: z.ZodOptional<z.ZodString>;
+                        swatchColor: z.ZodOptional<z.ZodString>;
+                        in_stock: z.ZodOptional<z.ZodBoolean>;
+                        inStock: z.ZodOptional<z.ZodBoolean>;
+                    }, z.core.$strip>>>;
+                    variantOptions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        name: z.ZodOptional<z.ZodString>;
+                        value: z.ZodOptional<z.ZodString>;
+                        option_value: z.ZodOptional<z.ZodString>;
+                        attribute_value: z.ZodOptional<z.ZodString>;
+                        type: z.ZodOptional<z.ZodString>;
+                        attribute: z.ZodOptional<z.ZodString>;
+                        option_name: z.ZodOptional<z.ZodString>;
+                        attribute_name: z.ZodOptional<z.ZodString>;
+                        variant_name: z.ZodOptional<z.ZodString>;
+                        sku: z.ZodOptional<z.ZodString>;
+                        price: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+                        price_discounted: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+                        image: z.ZodOptional<z.ZodString>;
+                        imageUrl: z.ZodOptional<z.ZodString>;
+                        image_url: z.ZodOptional<z.ZodString>;
+                        color: z.ZodOptional<z.ZodString>;
+                        colour: z.ZodOptional<z.ZodString>;
+                        color_hex: z.ZodOptional<z.ZodString>;
+                        hex: z.ZodOptional<z.ZodString>;
+                        swatch: z.ZodOptional<z.ZodString>;
+                        swatchColor: z.ZodOptional<z.ZodString>;
+                        in_stock: z.ZodOptional<z.ZodBoolean>;
+                        inStock: z.ZodOptional<z.ZodBoolean>;
+                    }, z.core.$strip>>>;
+                    variant_options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        name: z.ZodOptional<z.ZodString>;
+                        value: z.ZodOptional<z.ZodString>;
+                        option_value: z.ZodOptional<z.ZodString>;
+                        attribute_value: z.ZodOptional<z.ZodString>;
+                        type: z.ZodOptional<z.ZodString>;
+                        attribute: z.ZodOptional<z.ZodString>;
+                        option_name: z.ZodOptional<z.ZodString>;
+                        attribute_name: z.ZodOptional<z.ZodString>;
+                        variant_name: z.ZodOptional<z.ZodString>;
+                        sku: z.ZodOptional<z.ZodString>;
+                        price: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+                        price_discounted: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+                        image: z.ZodOptional<z.ZodString>;
+                        imageUrl: z.ZodOptional<z.ZodString>;
+                        image_url: z.ZodOptional<z.ZodString>;
+                        color: z.ZodOptional<z.ZodString>;
+                        colour: z.ZodOptional<z.ZodString>;
+                        color_hex: z.ZodOptional<z.ZodString>;
+                        hex: z.ZodOptional<z.ZodString>;
+                        swatch: z.ZodOptional<z.ZodString>;
+                        swatchColor: z.ZodOptional<z.ZodString>;
+                        in_stock: z.ZodOptional<z.ZodBoolean>;
+                        inStock: z.ZodOptional<z.ZodBoolean>;
+                    }, z.core.$strip>>>;
+                    productVariants: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        name: z.ZodOptional<z.ZodString>;
+                        value: z.ZodOptional<z.ZodString>;
+                        option_value: z.ZodOptional<z.ZodString>;
+                        attribute_value: z.ZodOptional<z.ZodString>;
+                        type: z.ZodOptional<z.ZodString>;
+                        attribute: z.ZodOptional<z.ZodString>;
+                        option_name: z.ZodOptional<z.ZodString>;
+                        attribute_name: z.ZodOptional<z.ZodString>;
+                        variant_name: z.ZodOptional<z.ZodString>;
+                        sku: z.ZodOptional<z.ZodString>;
+                        price: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+                        price_discounted: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+                        image: z.ZodOptional<z.ZodString>;
+                        imageUrl: z.ZodOptional<z.ZodString>;
+                        image_url: z.ZodOptional<z.ZodString>;
+                        color: z.ZodOptional<z.ZodString>;
+                        colour: z.ZodOptional<z.ZodString>;
+                        color_hex: z.ZodOptional<z.ZodString>;
+                        hex: z.ZodOptional<z.ZodString>;
+                        swatch: z.ZodOptional<z.ZodString>;
+                        swatchColor: z.ZodOptional<z.ZodString>;
+                        in_stock: z.ZodOptional<z.ZodBoolean>;
+                        inStock: z.ZodOptional<z.ZodBoolean>;
+                    }, z.core.$strip>>>;
+                    product_variants: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        name: z.ZodOptional<z.ZodString>;
+                        value: z.ZodOptional<z.ZodString>;
+                        option_value: z.ZodOptional<z.ZodString>;
+                        attribute_value: z.ZodOptional<z.ZodString>;
+                        type: z.ZodOptional<z.ZodString>;
+                        attribute: z.ZodOptional<z.ZodString>;
+                        option_name: z.ZodOptional<z.ZodString>;
+                        attribute_name: z.ZodOptional<z.ZodString>;
+                        variant_name: z.ZodOptional<z.ZodString>;
+                        sku: z.ZodOptional<z.ZodString>;
+                        price: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+                        price_discounted: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+                        image: z.ZodOptional<z.ZodString>;
+                        imageUrl: z.ZodOptional<z.ZodString>;
+                        image_url: z.ZodOptional<z.ZodString>;
+                        color: z.ZodOptional<z.ZodString>;
+                        colour: z.ZodOptional<z.ZodString>;
+                        color_hex: z.ZodOptional<z.ZodString>;
+                        hex: z.ZodOptional<z.ZodString>;
+                        swatch: z.ZodOptional<z.ZodString>;
+                        swatchColor: z.ZodOptional<z.ZodString>;
+                        in_stock: z.ZodOptional<z.ZodBoolean>;
+                        inStock: z.ZodOptional<z.ZodBoolean>;
+                    }, z.core.$strip>>>;
+                    url: z.ZodOptional<z.ZodString>;
+                    cartCode: z.ZodOptional<z.ZodString>;
+                    description: z.ZodOptional<z.ZodString>;
+                    description_html: z.ZodOptional<z.ZodString>;
+                    descriptionHtml: z.ZodOptional<z.ZodString>;
+                    facet_hits: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                    facetHits: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                    features: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        name: z.ZodOptional<z.ZodString>;
+                        key: z.ZodOptional<z.ZodString>;
+                        label: z.ZodOptional<z.ZodString>;
+                        value: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+                    }, z.core.$strip>>>;
+                    specifications: z.ZodOptional<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodString>, z.ZodArray<z.ZodObject<{
+                        key: z.ZodString;
+                        value: z.ZodString;
+                    }, z.core.$strip>>]>>;
+                }, z.core.$strip>>;
+                action: z.ZodOptional<z.ZodObject<{
+                    title: z.ZodString;
+                    type: z.ZodString;
+                    payload: z.ZodOptional<z.ZodUnknown>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>;
+            readonly description: "Full product detail view with images, specs, variants, and purchase actions.";
+        };
+        readonly ProductGrid: {
+            readonly schema: z.ZodObject<{
+                endOfList: z.ZodOptional<z.ZodBoolean>;
+                rankingState: z.ZodOptional<z.ZodEnum<{
+                    pending: "pending";
+                    final: "final";
+                }>>;
+                sequenceId: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>;
+            readonly description: "A scrollable grid of ProductCard children with optional \"more\" pagination.";
+        };
+        readonly ReviewHighlights: {
+            readonly schema: z.ZodObject<{
+                reviews: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    review_class: z.ZodOptional<z.ZodString>;
+                    review_text: z.ZodOptional<z.ZodString>;
+                    review_rating: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+                    review_tag: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>;
+            readonly description: "A list of highlighted customer reviews with sentiment and ratings.";
+        };
+        readonly ProsAndCons: {
+            readonly schema: z.ZodObject<{
+                productName: z.ZodOptional<z.ZodString>;
+                pros: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                cons: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>;
+            readonly description: "A pros and cons list for a product.";
+        };
+        readonly CategoriesContainer: {
+            readonly schema: z.ZodObject<{
+                groups: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    groupName: z.ZodString;
+                    image: z.ZodOptional<z.ZodString>;
+                    description: z.ZodOptional<z.ZodString>;
+                    highlight: z.ZodOptional<z.ZodString>;
+                    labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    products: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+                }, z.core.$strip>>>;
+                filterTags: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    title: z.ZodString;
+                    action: z.ZodOptional<z.ZodObject<{
+                        title: z.ZodString;
+                        type: z.ZodString;
+                        payload: z.ZodOptional<z.ZodUnknown>;
+                    }, z.core.$strip>>;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>;
+            readonly description: "Tabbed product groups with optional filter tag buttons.";
+        };
+        readonly HandoffNotice: {
+            readonly schema: z.ZodObject<{
+                summary: z.ZodOptional<z.ZodString>;
+                products_discussed: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                user_sentiment: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>;
+            readonly description: "A notice shown when the conversation is escalated to a human agent.";
+        };
+        readonly PanelRestoreCard: {
+            readonly schema: z.ZodObject<{
+                eyebrow: z.ZodOptional<z.ZodString>;
+                title: z.ZodOptional<z.ZodString>;
+                showTitle: z.ZodOptional<z.ZodBoolean>;
+                ctaLabel: z.ZodOptional<z.ZodString>;
+                panelMessageId: z.ZodString;
+                highlightMessageId: z.ZodOptional<z.ZodString>;
+                threadId: z.ZodOptional<z.ZodString>;
+                products: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    imageUrl: z.ZodOptional<z.ZodString>;
+                    name: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>;
+            readonly description: "A frontend-owned transcript card that reopens a related panel snapshot.";
+        };
+        readonly PhotoAnalysisCard: {
+            readonly schema: z.ZodObject<{
+                summary: 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>;
+                next_question: z.ZodOptional<z.ZodString>;
+                style_images: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>;
+            readonly description: "Structured photo analysis card with strengths, focus points, celeb vibe, and follow-up question.";
+        };
+        readonly BeautyPhotoStep: {
+            readonly schema: z.ZodObject<{
+                processing: z.ZodOptional<z.ZodBoolean>;
+                title: z.ZodOptional<z.ZodString>;
+                description: z.ZodOptional<z.ZodString>;
+                upload_label: z.ZodOptional<z.ZodString>;
+                skip_label: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>;
+            readonly description: "Transient selfie upload prompt for beauty consulting init flow.";
+        };
+    };
+};
+export type ChatCatalog = typeof chatCatalog;
+export type ChatComponentName = keyof ChatCatalog['components'];

package/dist/chat/chat-presentation-state.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Centralized chat presentation state (focus thread, scroll requests, read hints).
+ * Purpose-aligned with the legacy Redux presentation slice, without Redux.
+ */
+export type GroupReadState = 'seen' | 'unseen' | 'active_unread' | 'overflow_unread';
+export type PresentationGroupMeta = {
+    id: string;
+    threadId: string;
+    readState: GroupReadState;
+    status: 'streaming' | 'complete';
+    updatedAt: number;
+};
+export type ScrollRequest = {
+    id: number;
+    type: 'thread' | 'bottom';
+    behavior: ScrollBehavior;
+    threadId?: string;
+};
+export declare class ChatPresentationState {
+    /** Per-assistant-thread read / streaming metadata */
+    groups: Record<string, PresentationGroupMeta>;
+    pinnedToBottom: boolean;
+    userInteracting: boolean;
+    /** When set, transcript UI may collapse other threads until released */
+    focusedThreadId: string | null;
+    /** Drawer / widget considered visible */
+    shown: boolean;
+    lastAutoAnchoredGroupId: string | null;
+    scrollRequest: ScrollRequest | null;
+    private _nextScrollId;
+    setShown(shown: boolean): void;
+    reset(): void;
+    registerAssistantActivity(threadId: string): void;
+    finalizeAssistantGroup(threadId: string): void;
+    setGroupReadStates(updates: Array<{
+        groupId: string;
+        readState: GroupReadState;
+    }>): void;
+    requestThreadFocus(threadId: string, behavior?: ScrollBehavior): void;
+    requestScrollToBottom(behavior?: ScrollBehavior): void;
+    consumeScrollRequest(id: number): void;
+    releaseFocusedThread(): void;
+    /** Align focus with rollback / thread without queuing scroll */
+    setFocusedThreadId(threadId: string | null): void;
+    markGroupAutoAnchored(groupId: string): void;
+    /** Block soft stream scroll when user pulled away from bottom */
+    shouldBlockStreamAutoScroll(): boolean;
+    getAssistantReadState(threadId: string): GroupReadState | undefined;
+}
+/**
+ * Latest assistant “group” with unread semantics (for auto-anchor).
+ */
+export declare function getLatestUnreadAssistantThreadId(orderedThreadIds: string[], state: ChatPresentationState): string | null;

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

@@ -0,0 +1,15 @@
+/**
+ * AI Grouping Cards renderer.
+ *
+ * Desktop: compact card with image, name, and labels.
+ * Mobile: simple button list with arrow prefix (images hidden via CSS).
+ *
+ * Note: The media-rail layout is similar to `AISuggestedSearchCards` but with different tokens;
+ * a shared primitive may be extracted later if the visual system stabilizes.
+ *
+ * XSS safety: All text is set via textContent. Image URLs are validated
+ * for safe protocols. No innerHTML.
+ */
+import type { UIElement } from '../../common/types.js';
+import type { ChatUISpecRenderContext } from '../types.js';
+export declare function renderAIGroupingCards(element: UIElement, ctx: ChatUISpecRenderContext): HTMLElement;

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

@@ -0,0 +1,13 @@
+/**
+ * AI Suggested Search Cards renderer.
+ *
+ * Cards with a larger image and a single clear title line.
+ * Secondary / tertiary supporting lines are intentionally omitted in chat so
+ * the module reads as a compact, visual category chooser.
+ *
+ * XSS safety: All text is set via textContent. Image URLs are validated
+ * for safe protocols. No innerHTML.
+ */
+import type { UIElement } from '../../common/types.js';
+import type { ChatUISpecRenderContext } from '../types.js';
+export declare function renderAISuggestedSearchCards(element: UIElement, ctx: ChatUISpecRenderContext): HTMLElement;

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

@@ -0,0 +1,9 @@
+/**
+ * AI Top Picks renderer.
+ *
+ * DOM/layout parity with robot-engine-lean MainPane/AIAnalysisZone TopPicksResults:
+ * article: role badge, image, title, rating, price, labels, hover CTA.
+ */
+import type { UIElement } from '../../common/types.js';
+import type { ChatUISpecRenderContext } from '../types.js';
+export declare function renderAITopPicks(element: UIElement, ctx: ChatUISpecRenderContext): HTMLElement;

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

@@ -0,0 +1,31 @@
+/**
+ * Beauty photo step card — a transient prompt rendered above the chat input
+ * asking the user to upload a selfie for skin/beauty analysis.
+ *
+ * The backend sends a `BeautyPhotoStep` UISpec during the beauty consulting
+ * init flow. The chat widget intercepts it and renders this component in a
+ * dedicated slot (not in the message stream or panel).
+ *
+ * Props (from UISpec):
+ *   processing  — boolean, disables upload button and shows processing label
+ *   title       — override heading text
+ *   description — override body text
+ *   upload_label — override upload button text
+ *   skip_label  — override skip button text
+ */
+import type { UIElement } from '../../common/types.js';
+import type { ChatUISpecRenderContext } from '../types.js';
+export interface BeautyPhotoStepProps {
+    processing: boolean;
+    title?: string | undefined;
+    description?: string | undefined;
+    uploadLabel?: string | undefined;
+    skipLabel?: string | undefined;
+}
+/** Extract typed props from a raw UISpec element props bag. */
+export declare function parseBeautyPhotoStepProps(props: Record<string, unknown>): BeautyPhotoStepProps;
+export interface BeautyPhotoStepCallbacks {
+    onUpload?: (() => void) | undefined;
+    onSkip?: (() => void) | undefined;
+}
+export declare function renderBeautyPhotoStep(element: UIElement, ctx: ChatUISpecRenderContext, callbacks?: BeautyPhotoStepCallbacks): HTMLElement;

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

@@ -0,0 +1,11 @@
+/**
+ * CategoriesContainer — renders grouped product lists with tab navigation
+ * and optional filter tags.
+ *
+ * The protocol adapter normalizes grouping payloads into this UISpec element.
+ *
+ * XSS safety: All text is set via textContent. No innerHTML.
+ */
+import type { UIElement } from '../../common/types.js';
+import type { ChatUISpecRenderContext } from '../types.js';
+export declare function renderCategoriesContainer(element: UIElement, context: ChatUISpecRenderContext): HTMLElement;