@gengage/assistant-fe 0.4.3 → 0.4.5

package/README.md

@@ -91,6 +91,8 @@ See [docs/native-mobile-sdk.md](docs/native-mobile-sdk.md) for iOS WKWebView, An
 | **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 |
 
+The chat widget includes a built-in history entry point in the header. Past chat sessions are stored per account/user in `localStorage`, while the active session restore cache continues to use IndexedDB for cross-navigation handoff flows.
+
 ---
 
 ## Customization
@@ -121,6 +123,7 @@ npm run koctascomtr                            # Merchant shortcut with the seed
 npm run trendyolcom                            # Another merchant shortcut using its default PDP SKU
 npm run typecheck                              # TypeScript strict check
 npm run test                                   # Unit tests
+npm run test:chat-history                      # Targeted history + restore regression suite
 npm run build                                  # Build to dist/
 npm run catalog                                # Visual component catalog at :3002
 npm run docs:build                             # Build contributor docs with VitePress

package/dist/chat/catalog.d.ts

@@ -365,6 +365,19 @@ export declare const HandoffNoticeSchema: z.ZodObject<{
     products_discussed: z.ZodOptional<z.ZodArray<z.ZodString>>;
     user_sentiment: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+export declare const PanelRestoreCardSchema: 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>;
 export declare const PhotoAnalysisCardSchema: z.ZodObject<{
     summary: z.ZodString;
     strengths: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -769,6 +782,22 @@ export declare const chatCatalog: {
             }, 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;

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

@@ -1,5 +1,4 @@
 import { ChatI18n, ChatMessage } from '../types.js';
-import { ThumbnailEntry } from './ThumbnailsColumn.js';
 /** Generic fallback icon (right-arrow) used when a pill specifies an icon name not in the map. */
 declare const DEFAULT_ACTION_ICON = "<svg viewBox=\"0 0 16 16\" class=\"gengage-chat-icon\"><path d=\"M3 8h10M9 4l4 4-4 4\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/></svg>";
 /** SVG icon map for suggested action chips/pills. Keys match backend icon names. */
@@ -31,6 +30,8 @@ export interface ChatDrawerOptions {
     /** When true, render the header favorites (heart) button. */
     showHeaderFavorites?: boolean | undefined;
     onFavoritesClick?: (() => void) | undefined;
+    /** Callback fired when the history button in the header is clicked. */
+    onHistoryClick?: (() => void) | undefined;
     /** Callback fired when the panel back button is clicked. */
     onPanelBack?: (() => void) | undefined;
     /** Callback fired when the panel forward button is clicked. */
@@ -48,10 +49,10 @@ export interface ChatDrawerOptions {
     getMobileState?: (() => 'half' | 'full') | undefined;
     /** Returns true when the chat is displayed as a mobile bottom-sheet. Used to keep the side-panel back button always enabled. */
     getMobileViewport?: (() => boolean) | undefined;
-    /** Callback fired when a product thumbnail is clicked (for thread rollback). */
-    onThumbnailClick?: ((threadId: string) => void) | undefined;
     /** Callback fired when a link in bot HTML is clicked. */
     onLinkClick?: ((url: string) => void) | undefined;
+    /** Render a frontend-owned message UI payload inside the bubble, when present. */
+    renderMessageUISpec?: ((message: ChatMessage) => HTMLElement | null) | undefined;
     /** Enable voice input (Web Speech API STT). Default: false. */
     voiceEnabled?: boolean | undefined;
     /** BCP 47 language for speech recognition. Default: 'tr-TR'. */
@@ -87,9 +88,7 @@ export declare class ChatDrawer {
     private _panelEl;
     private _panelVisible;
     private _panelCollapsed;
-    private _dividerPreviewEnabled;
     private _dividerEl;
-    private _dividerPreviewEl;
     private _onPanelToggle;
     private _onHostShellSync;
     private _pendingAttachment;
@@ -105,7 +104,6 @@ export declare class ChatDrawer {
     private _userScrolledUp;
     private _scrollLockedUntil;
     private _inputChipsEl;
-    private _thumbnailsColumn;
     private _panelFloatingEl;
     /** Mobile: overlay host for comparison dock (above panel scroll; avoids transformed panel containing block). */
     private _comparisonDockSlotEl;
@@ -227,7 +225,7 @@ export declare class ChatDrawer {
     /**
      * Targeted content swap for an already-visible panel. Replaces the skeleton
      * or the current content element with `el`, leaving topbar / AI zone /
-     * thumbnails column / floating element attached. Also resets topbar actions
+     * floating element attached. Also resets topbar actions
      * because the incoming content provides its own toolbar.
      */
     private _swapPanelContent;
@@ -242,7 +240,7 @@ export declare class ChatDrawer {
     resyncPanelTopBarFromCurrentContent(): void;
     /** Whether the panel is currently visible (may be empty). */
     isPanelVisible(): boolean;
-    /** Whether the panel is currently visible and has rendered content (beyond topbar + thumbnails column). */
+    /** Whether the panel is currently visible and has rendered content beyond chrome elements. */
     hasPanelContent(): boolean;
     /** Whether panel currently shows loading skeleton blocks. */
     isPanelLoading(): boolean;
@@ -260,6 +258,7 @@ export declare class ChatDrawer {
      * Keeps `_panelCollapsed` untouched so user collapse preference survives future panel renders.
      */
     clearPanel(): void;
+    private _syncComparisonDockVisibility;
     /**
      * Mobile-only slot (see CSS): pins the comparison dock above panel scroll.
      * Pass null to clear.
@@ -271,6 +270,7 @@ export declare class ChatDrawer {
      */
     hideMobilePanel(): void;
     private _showMobilePanelFromBtn;
+    showMobilePanel(): void;
     /** Expand panel without locking — user can still toggle via divider. */
     expandPanel(): void;
     /**
@@ -284,6 +284,7 @@ export declare class ChatDrawer {
      * case subsequent DOM mutations (appended children, layout) shift it.
      */
     private _smoothScrollPanelListToTop;
+    private _getChoicePrompterRevealScrollThreshold;
     /** Update scroll affordance (bottom fade gradient) on the panel. */
     private _updateScrollAffordance;
     /** Horizontal swipe on conversation/panel areas to toggle the panel (mobile only). */
@@ -294,7 +295,6 @@ export declare class ChatDrawer {
     isPanelCollapsed(): boolean;
     /** Programmatically set panel collapsed state. */
     setPanelCollapsed(collapsed: boolean): void;
-    setDividerPreviewEnabled(enabled: boolean): void;
     /** Save panel collapsed state to sessionStorage. */
     persistPanelState(accountId: string): void;
     /** Restore panel collapsed state from sessionStorage. Returns true when restored as collapsed. */
@@ -347,10 +347,6 @@ export declare class ChatDrawer {
     }>): void;
     /** Clear input-area chips. */
     clearInputAreaChips(): void;
-    setThumbnails(entries: ThumbnailEntry[]): void;
-    hideThumbnails(): void;
-    private _renderDividerPreview;
-    private _syncDividerPreview;
     /** Activate focus trap — Tab/Shift+Tab cycles within the drawer. */
     trapFocus(): void;
     /** Release the focus trap and restore previously focused element. */

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

@@ -0,0 +1,4 @@
+import { UIElement } from '../../common/types.js';
+import { ChatUISpecRenderContext } from '../types.js';
+export declare const FRONTEND_PANEL_RESTORE_ACTION = "frontend_restore_panel_message";
+export declare function renderPanelRestoreCard(element: UIElement, ctx: ChatUISpecRenderContext): HTMLElement;

package/dist/chat/history-storage.d.ts

@@ -0,0 +1,85 @@
+import { BackendContext, UISpec } from '../common/types.js';
+import { ChatMessage } from './types.js';
+type LegacyThumbnailEntry = {
+    sku: string;
+    imageUrl: string;
+    threadId: string;
+};
+export interface StoredHistoryMessage {
+    id: string;
+    threadId?: string | undefined;
+    role: 'user' | 'assistant';
+    content?: string | undefined;
+    uiSpec?: UISpec | undefined;
+    frontendOnly?: boolean | undefined;
+    silent?: boolean | undefined;
+    renderHint?: string | undefined;
+    photoAnalysis?: {
+        summary: string;
+        strengths?: string[];
+        focusPoints?: string[];
+        celebStyle?: string;
+        celebStyleReason?: string;
+        nextQuestion?: string;
+    } | undefined;
+    timestamp: number;
+    status: 'done' | 'error';
+}
+export interface ChatHistoryIndexEntry {
+    id: string;
+    title: string;
+    preview: string;
+    createdAt: string;
+    updatedAt: string;
+    messageCount: number;
+    pageType?: string | undefined;
+    sku?: string | undefined;
+    sourceSessionId: string;
+}
+export interface ChatHistorySessionRecord extends ChatHistoryIndexEntry {
+    version: number;
+    userId: string;
+    appId: string;
+    messages: StoredHistoryMessage[];
+    currentThreadId: string | null;
+    lastThreadId: string | null;
+    panelThreads?: string[] | undefined;
+    /** Legacy thumbnail-strip data kept optional for backward compatibility with older local history. */
+    thumbnailEntries?: LegacyThumbnailEntry[] | undefined;
+    panelSnapshotHtml?: Record<string, string> | undefined;
+    panelSnapshotTypes?: Record<string, string> | undefined;
+    panelAiSpecByThread?: Record<string, UISpec> | undefined;
+    lastBackendContext: BackendContext | null;
+}
+export interface SaveHistorySessionParams {
+    historyId: string;
+    userId: string;
+    appId: string;
+    sourceSessionId: string;
+    messages: ChatMessage[];
+    currentThreadId: string | null;
+    lastThreadId: string | null;
+    chatCreatedAt: string;
+    panelSnapshots: Map<string, HTMLElement>;
+    panelSnapshotTypes: Map<string, string>;
+    panelThreads: string[];
+    panelAiSpecByThread?: Map<string, UISpec> | undefined;
+    lastBackendContext: BackendContext | null;
+    pageType?: string | undefined;
+    sku?: string | undefined;
+}
+export declare class ChatHistoryStorage {
+    private readonly _appId;
+    private readonly _userId;
+    private readonly _storage;
+    private readonly _scope;
+    constructor(_appId: string, _userId: string, _storage?: Storage | null);
+    createHistoryId(): string;
+    findSessionId(sourceSessionId: string, createdAt: string): string | null;
+    listSessions(): ChatHistoryIndexEntry[];
+    loadSession(historyId: string): ChatHistorySessionRecord | null;
+    saveSession(params: SaveHistorySessionParams): ChatHistorySessionRecord | null;
+    deleteSession(historyId: string): void;
+    private _commitRecord;
+}
+export {};

package/dist/chat/index.d.ts

@@ -63,9 +63,11 @@ export declare class GengageChat extends BaseWidget<ChatWidgetConfig> {
     private _comparisonSelectedSkus;
     private _comparisonSelectionWarning;
     private _comparisonRefreshRafId;
+    private _lastAppliedKeyboardInset;
     /** SKUs of products the user has viewed across panel product grids. */
     private _viewedProductSkus;
-    private _thumbnailEntries;
+    /** Latest AI analysis UISpec (AITopPicks/AIGroupingCards) per thread for panel restore. */
+    private _panelAiSpecByThread;
     private _choicePrompterEl;
     private _openState;
     private _mobileBreakpoint;
@@ -113,6 +115,10 @@ export declare class GengageChat extends BaseWidget<ChatWidgetConfig> {
     private _currentPanelSource;
     /** IndexedDB session persistence manager. */
     private _session;
+    /** LocalStorage-backed chat history manager. */
+    private _historyStorage;
+    /** Active local history session ID for the current conversation. */
+    private _activeHistorySessionId;
     /** Transcript focus, pin-to-bottom, and scroll request coordination. */
     private readonly _presentation;
     /** Registered event callbacks (GA4 event hooks). Key = event name, value = set of callbacks. */
@@ -169,8 +175,12 @@ export declare class GengageChat extends BaseWidget<ChatWidgetConfig> {
      * delay or distort the next response.
      */
     private _pruneEmptyStreamingAssistantPlaceholders;
+    /** Clear all runtime conversation state while keeping the widget mounted and ready. */
+    private _clearConversationState;
     /** Reset all chat state when navigating to a different SKU/page. */
     private _resetForNewPage;
+    /** Start a brand-new local conversation on the current page context. */
+    private _startNewChat;
     /**
      * Same side effects as stream UISpec `clearPanel`: hide/clear the assistant panel without
      * `restoreOrClearPanel()`. Used for `clearPanel` chunks and PDP chat layout (`productDetailsExtended` off).
@@ -262,9 +272,20 @@ export declare class GengageChat extends BaseWidget<ChatWidgetConfig> {
     private _applyPanelListHeadingToContext;
     private _renderPanelFromSource;
     private _handleRollback;
+    private _ensureMobileFullSheetForPanel;
+    private _ensureMobilePanelOverlayVisible;
     private _ensurePdpPrimeSuggestedUiIfNeeded;
     /** Rewind the conversation to the given thread. */
     private _rollbackToThread;
+    private _persistHistoryToLocalStorage;
+    private _persistConversationState;
+    private _persistConversationStateForNavigation;
+    private _formatHistoryTimestamp;
+    private _openHistoryPanel;
+    private _buildHistoryPageEl;
+    private _deleteHistorySession;
+    private _loadHistorySession;
+    private _restoreFromHistoryRecord;
     private _persistToIndexedDB;
     private _isSameOriginUrl;
     private _markUnavailableProductContext;
@@ -289,8 +310,6 @@ export declare class GengageChat extends BaseWidget<ChatWidgetConfig> {
      * then fall back to thread-level history.
      */
     private _navigatePanelBack;
-    private _shouldUseDividerPreviewForSpec;
-    private _shouldUseDividerPreviewForSource;
     private _toggleComparisonSku;
     /**
      * Refresh the panel DOM to reflect the current comparison state without
@@ -318,6 +337,15 @@ export declare class GengageChat extends BaseWidget<ChatWidgetConfig> {
     private _toggleProductFavorite;
     private _openFavoritesPanel;
     private _buildFavoritesPageEl;
+    private _isMessageHostedUISpec;
+    private _isPanelAiSpec;
+    private _rememberPanelAiSpec;
+    private _restorePanelAiSpecMap;
+    private _hydrateRestoredUISpecMetadata;
+    private _renderMessageUISpec;
+    private _maybeAddPanelRestoreMessage;
+    private _restorePanelFromFrontendMessage;
+    private _restorePanelAiZoneForThread;
     /**
      * Run registered callbacks for a GA4 event.
      * If any callback returns false or throws, handle the failure (e.g. show error for cart-add).

package/dist/chat/panel-manager.d.ts

@@ -42,7 +42,7 @@ export declare class PanelManager {
      * Also restores the panel topbar title for the snapshot's component type.
      * Returns true if the snapshot was found and restored.
      */
-    restoreForMessage(messageId: string): boolean;
+    restoreForMessage(messageId: string, highlightMessageId?: string): boolean;
     /**
      * Send maximize-pdp / minify-pdp bridge messages with production-matching delays.
      * Called by the extended mode manager when panel extension state changes.

package/dist/chat/session-persistence.d.ts

@@ -2,7 +2,6 @@ import { GengageIndexedDB, FavoriteData } from '../common/indexed-db.js';
 import { CommunicationBridge } from '../common/communication-bridge.js';
 import { BackendContext, UISpec } from '../common/types.js';
 import { ChatMessage } from './types.js';
-import { ThumbnailEntry } from './components/ThumbnailsColumn.js';
 export type { FavoriteData };
 type NavigateFn = (url: string) => void;
 export interface PersistSessionParams {
@@ -14,8 +13,9 @@ export interface PersistSessionParams {
     lastThreadId: string | null;
     chatCreatedAt: string;
     panelSnapshots: Map<string, HTMLElement>;
+    panelSnapshotTypes?: Map<string, string> | undefined;
     panelThreads: string[];
-    thumbnailEntries: ThumbnailEntry[];
+    panelAiSpecByThread?: Map<string, UISpec> | undefined;
     lastBackendContext: BackendContext | null;
     sku?: string | undefined;
 }

package/dist/chat/types.d.ts

@@ -71,7 +71,7 @@ export interface ChatWidgetConfig extends BaseWidgetConfig {
     /**
      * Panel display mode:
      *   - 'auto'      : Panel appears/hides with content; user can toggle (default)
-     *   - 'collapsed'  : Panel starts collapsed; user can expand
+     *   - 'collapsed'  : Panel starts collapsed; fresh panel content reopens it
      *   - 'expanded'   : Panel starts expanded (users can still collapse/expand)
      */
     panelMode?: 'auto' | 'collapsed' | 'expanded';
@@ -239,6 +239,11 @@ export interface ChatI18n {
     offlineMessage: string;
     cartAriaLabel: string;
     favoritesAriaLabel: string;
+    historyAriaLabel: string;
+    historyPageTitle: string;
+    emptyHistoryMessage: string;
+    historyDeleteLabel: string;
+    historyDeleteConfirmMessage: string;
     showPanelAriaLabel: string;
     addToFavoritesLabel: string;
     customerReviewsTitle: string;
@@ -352,7 +357,7 @@ export interface ChatUISpecRenderContext {
     hideProductDiscountBadge?: boolean | undefined;
     hideUserReviews?: boolean | undefined;
     hideStockStatus?: boolean | 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' | 'consultingOtherCompatibleProductsLabel' | 'consultingFallbackGroupLabel' | 'consultingFallbackStyleLabel' | 'consultingStyleLoadingDescription' | 'consultingStyleUnavailableDescription' | 'consultingStyleLoadingBadge' | 'consultingStyleUnavailableBadge' | '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' | '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' | 'consultingOtherCompatibleProductsLabel' | 'consultingFallbackGroupLabel' | 'consultingFallbackStyleLabel' | 'consultingStyleLoadingDescription' | 'consultingStyleUnavailableDescription' | 'consultingStyleLoadingBadge' | 'consultingStyleUnavailableBadge' | 'viewMoreLabel' | 'similarProductsLabel' | 'addToCartButton' | 'shareButton' | 'productInfoTab' | 'specificationsTab' | 'recommendedChoiceLabel' | 'highlightsLabel' | 'keyDifferencesLabel' | 'specialCasesLabel' | 'emptyReviewsMessage' | 'closeAriaLabel' | 'dismissAriaLabel' | 'startChatLabel' | 'handoffHeading' | 'customerReviewsTitle' | 'addToFavoritesLabel' | 'showPanelAriaLabel' | 'reviewFilterPositive' | 'reviewFilterNegative' | 'decreaseLabel' | 'increaseLabel' | 'reviewCustomersMentionSingular' | 'reviewCustomersMentionPlural' | 'reviewSubjectsHeading' | 'aiBrowseCategoriesTitle' | 'photoAnalysisBadge' | 'photoAnalysisStrengthsLabel' | 'photoAnalysisFocusLabel' | 'photoAnalysisCelebStyleLabel' | 'beautyPhotoStepTitle' | 'beautyPhotoStepDescription' | 'beautyPhotoStepUpload' | 'beautyPhotoStepProcessing' | 'beautyPhotoStepSkip'>;
     productSort?: ProductSortState | undefined;
     onSortChange?: ((sort: ProductSortState) => void) | undefined;
     comparisonSelectMode?: boolean | undefined;
@@ -384,6 +389,8 @@ export interface ChatMessage {
     content?: string;
     /** json-render UI spec attached to this message (e.g. product cards). */
     uiSpec?: import('../common/types.js').UISpec;
+    /** Frontend-synthesized visible message; exclude from backend chat history. */
+    frontendOnly?: boolean;
     /** Image attachment (user-uploaded). Stored in-memory until send. */
     attachment?: File;
     /** Snapshot of panel DOM at time this message's stream completed. */
@@ -420,6 +427,7 @@ export interface SerializableChatMessage {
     threadId?: string | undefined;
     role: 'user' | 'assistant';
     content?: string | undefined;
+    frontendOnly?: boolean | undefined;
     silent?: boolean | undefined;
     timestamp: number;
     status: 'streaming' | 'done' | 'error';