@gymmymac/bob-widget 2.0.0 → 3.0.0

package/README.md

@@ -2,6 +2,18 @@
 
 AI-powered automotive parts assistant widget for integration into partner websites.
 
+**v3.0.0** - Major release with multi-tenant support, RAF animations, swipeable Bob, and enhanced mobile experience.
+
+## What's New in v3.0.0
+
+- 🎭 **SwipeableBob**: Gesture-based interactions - swipe Bob away or back into view
+- 🏢 **Multi-Tenant Support**: Configurable looks and animations per tenant
+- 🎬 **RAF Animations**: Smooth 60fps animations using requestAnimationFrame
+- ⚡ **MatrixProductLoader**: Cyberpunk-style loading with phased states
+- 🔥 **SparkDealBanner**: Animated promotional banners
+- 👋 **Returning User Detection**: Personalized greetings for repeat visitors
+- 🎨 **Theme Settings**: Dynamic theme configuration from database
+
 ## Installation
 
 ```bash
@@ -84,13 +96,13 @@ Or programmatically:
 ```tsx
 import { BOB_VERSION, getBobVersion } from '@gymmymac/bob-widget';
 
-console.log(`Bob Widget Version: ${getBobVersion()}`); // e.g., "1.1.4"
+console.log(`Bob Widget Version: ${getBobVersion()}`); // "3.0.0"
 ```
 
 Check the console for startup logs:
 ```
-[BobWidget] Package loaded - v1.1.4
-[BobWidget] v1.1.4 initialized
+[BobWidget] Package loaded - v3.0.0
+[BobWidget] v3.0.0 initialized
 [BobWidget] QueryClient: internal
 ```
 
@@ -211,10 +223,14 @@ function App() {
 
 ## Dependencies
 
-Bob Widget v1.1.4+ bundles its own dependencies. You only need:
+Bob Widget v3.0.0+ bundles its own dependencies. You only need:
 - `react` ^18.0.0
 - `react-dom` ^18.0.0
 
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for version history.
+
 ## Integration Guide
 
 For detailed integration instructions, see [CARFIX-INTEGRATION.md](./CARFIX-INTEGRATION.md).

package/dist/BobProvider.d.ts

@@ -93,6 +93,12 @@ export declare function useBobContext(): BobContextValue;
  * Hook to access Bob's Supabase client
  */
 export declare function useBobSupabase(): SupabaseClient;
+/**
+ * Hook to safely access Bob's Supabase client
+ * Returns null instead of throwing when used outside BobProvider
+ * Use this in widget components that need to work without BobProvider
+ */
+export declare function useBobSupabaseSafe(): SupabaseClient | null;
 /**
  * Hook to access host context
  */

package/dist/components/BobSuggestions.d.ts

@@ -0,0 +1,15 @@
+import { default as React } from 'react';
+import { Product } from '../types/product';
+
+interface BobSuggestionsProps {
+    products: Product[];
+    title?: string;
+    onProductClick?: (product: Product) => void;
+    onAddToCart?: (product: Product) => void;
+}
+/**
+ * Displays products Bob is actively recommending - styled to match CARFIX website.
+ * Rendered inline within chat messages when Bob presents specific products.
+ */
+export declare const BobSuggestions: React.FC<BobSuggestionsProps>;
+export default BobSuggestions;

package/dist/components/ChatInterface.d.ts

@@ -1,5 +1,6 @@
 import { default as React } from 'react';
 import { Message } from '../types/message';
+import { Product } from '../types/product';
 
 interface ChatInterfaceProps {
     messages: Message[];
@@ -15,6 +16,8 @@ interface ChatInterfaceProps {
     onToggleMute?: () => void;
     isSpeaking?: boolean;
     className?: string;
+    onAddToCart?: (product: Product) => void;
+    onProductClick?: (product: Product) => void;
 }
 export declare const ChatInterface: React.FC<ChatInterfaceProps>;
 export {};

package/dist/components/MatrixProductLoader.d.ts

@@ -0,0 +1,14 @@
+import { default as React } from 'react';
+import { SparkDeal } from '../hooks/useSparkDeals';
+
+export type LoaderPhase = 'hidden' | 'researching' | 'loading' | 'success';
+interface MatrixProductLoaderProps {
+    phase: LoaderPhase;
+    message?: string;
+    onComplete?: () => void;
+    onSparkDealClick?: (deal: SparkDeal) => void;
+    /** Optional product/brand names for subliminal messaging */
+    subliminalBrands?: string[];
+}
+export declare const MatrixProductLoader: React.FC<MatrixProductLoaderProps>;
+export default MatrixProductLoader;

package/dist/components/ProductBadge.d.ts

@@ -0,0 +1,15 @@
+import { default as React } from 'react';
+import { BADGE_CONFIG } from '../styles/carfix-tokens';
+
+type BadgeType = keyof typeof BADGE_CONFIG;
+interface ProductBadgeProps {
+    type: BadgeType;
+    value?: string;
+    className?: string;
+}
+/**
+ * Consistent badge component for product attributes
+ * Matches CARFIX website styling exactly
+ */
+export declare const ProductBadge: React.FC<ProductBadgeProps>;
+export default ProductBadge;

package/dist/components/ProductTile.d.ts

@@ -0,0 +1,20 @@
+import { default as React } from 'react';
+import { Product } from '../types';
+
+interface ProductTileProps {
+    product: Product;
+    isSpotlighted?: boolean;
+    onProductClick?: (product: Product) => void;
+    onAddToCart?: (product: Product) => void;
+}
+/**
+ * ProductTile - Premium Glassmorphism Product Cards
+ *
+ * iOS 26-inspired liquid glass design:
+ * - Frosted translucent glass with backdrop blur
+ * - Sharp white text with high contrast
+ * - CARFIX orange price highlights
+ * - Hover: scale(1.04), translateY(-4px), enhanced glow
+ */
+export declare const ProductTile: React.FC<ProductTileProps>;
+export {};

package/dist/components/SparkDealBanner.d.ts

@@ -0,0 +1,14 @@
+import { default as React } from 'react';
+import { SparkDeal } from '../hooks/useSparkDeals';
+import { MatrixTheme } from '../hooks/useThemeSettings';
+
+interface SparkDealBannerProps {
+    deals: SparkDeal[];
+    currentDealIndex: number;
+    onDealChange: (index: number) => void;
+    onDealClick: (deal: SparkDeal) => void;
+    scrollSpeed: number;
+    theme: Partial<MatrixTheme>;
+}
+export declare const SparkDealBanner: React.FC<SparkDealBannerProps>;
+export default SparkDealBanner;

package/dist/components/SwipeableBob.d.ts

@@ -0,0 +1,24 @@
+import { default as React } from 'react';
+import { BobPosition } from './mobile/MobileBobCharacter';
+
+interface SwipeableBobProps {
+    children: React.ReactNode;
+    isSpeaking?: boolean;
+    hasProducts?: boolean;
+    onVisibilityChange?: (visible: boolean) => void;
+    onPositionChange?: (position: BobPosition) => void;
+    currentPosition?: BobPosition;
+}
+/**
+ * SwipeableBob - Phase 2: Swipeable Bob Overlay with 3-Position System
+ *
+ * Features:
+ * - Swipe left to hide Bob (center → partial-left → hidden)
+ * - Swipe right to show Bob (hidden → partial-left → center)
+ * - Vertical "BOB" tab on left edge when hidden
+ * - Auto-reappear when TTS starts speaking
+ * - Auto-move to partial-left when products appear
+ * - Spring animation for slide in/out
+ */
+export declare const SwipeableBob: React.FC<SwipeableBobProps>;
+export {};

package/dist/components/mobile/ContainedChatDrawer.d.ts

@@ -16,8 +16,8 @@ interface ContainedChatDrawerProps {
     isSpeaking?: boolean;
 }
 /**
- * ContainedChatDrawer - Chat drawer using absolute positioning
- * Stays within parent container bounds instead of viewport.
+ * ContainedChatDrawer - Premium Glassmorphism Chat Drawer
+ * iOS 26 liquid glass design with CARFIX branding
  */
 export declare const ContainedChatDrawer: React.FC<ContainedChatDrawerProps>;
 export {};

package/dist/components/mobile/MobileBobCharacter.d.ts

@@ -1,13 +1,24 @@
 import { default as React } from 'react';
 
+export type BobPosition = 'center' | 'partial-left' | 'hidden';
 interface MobileBobCharacterProps {
     currentImage: string;
     animationState: string;
     counterOverlayUrl?: string;
     counterHeightPercent?: number;
     scale?: number;
-    position?: 'center' | 'left';
+    position?: BobPosition;
     verticalOffset?: number;
+    /** Theatrical entrance - controls fade-in opacity */
+    hasArrived?: boolean;
 }
+/**
+ * MobileBobCharacter - Bob with 3-position system
+ *
+ * Positions:
+ * - center: Bob centered on screen (welcome/idle state)
+ * - partial-left: Bob slides left, ~30% visible (products displayed)
+ * - hidden: Bob fully off-screen left (user swiped, full product view)
+ */
 export declare const MobileBobCharacter: React.FC<MobileBobCharacterProps>;
 export {};

package/dist/components/mobile/MobileBobLayoutCore.d.ts

@@ -0,0 +1,39 @@
+import { default as React } from 'react';
+import { BobPosition } from './MobileBobCharacter';
+import { Product, ServicePackage } from '../../types';
+import { HighlightedProduct } from '../../types/message';
+import { Vehicle } from '../../types/vehicle';
+
+interface MobileBobLayoutCoreProps {
+    currentImage: string;
+    animationState: string;
+    backdropUrl?: string;
+    counterOverlayUrl?: string;
+    counterHeightPercent?: number;
+    products: Product[];
+    servicePackages: ServicePackage[];
+    highlightedPartType?: string | null;
+    highlightedProduct?: HighlightedProduct | null;
+    onProductClick?: (product: Product) => void;
+    onPackageSelect?: (pkg: ServicePackage) => void;
+    isResearching?: boolean;
+    onAddToCart?: (product: Product) => void;
+    onNavigateToProductPage?: (product: Product) => void;
+    vehicle?: Vehicle | null;
+    onChangeVehicle?: () => void;
+    bobOffset?: number;
+    bobScale?: number;
+    bobHasArrived?: boolean;
+    externalBobPosition?: BobPosition;
+    onBobPositionChange?: (position: BobPosition) => void;
+}
+/**
+ * MobileBobLayoutCore - Bob character, backdrop, and products with 3-position system.
+ *
+ * Bob Positions:
+ * - center: Welcome/idle state, no products
+ * - partial-left: Products visible, Bob partially off-screen
+ * - hidden: User swiped, full product view
+ */
+export declare const MobileBobLayoutCore: React.FC<MobileBobLayoutCoreProps>;
+export {};

package/dist/components/mobile/MobileChatDrawer.d.ts

@@ -1,5 +1,6 @@
 import { default as React } from 'react';
 import { Message } from '../../types/message';
+import { Product } from '../../types/product';
 
 interface MobileChatDrawerProps {
     messages: Message[];
@@ -14,6 +15,8 @@ interface MobileChatDrawerProps {
     isMuted?: boolean;
     onToggleMute?: () => void;
     isSpeaking?: boolean;
+    onAddToCart?: (product: Product) => void;
+    onProductClick?: (product: Product) => void;
 }
 export declare const MobileChatDrawer: React.FC<MobileChatDrawerProps>;
 export {};

package/dist/components/mobile/MobileProductColumn.d.ts

@@ -13,6 +13,7 @@ interface MobileProductColumnProps {
     visible?: boolean;
     counterHeightPercent?: number;
     hasVehicle?: boolean;
+    onAddToCart?: (product: Product | Product[]) => void;
 }
 export declare const MobileProductColumn: React.FC<MobileProductColumnProps>;
 export {};

package/dist/components/mobile/ServicePackageDetailView.d.ts

@@ -0,0 +1,31 @@
+import { default as React } from 'react';
+import { PreparedTier, PreparedTierProduct } from '../../types/product';
+
+/**
+ * Service package interface - preparedTiers is the ONLY source of truth
+ */
+interface ServicePackageDetail {
+    id: string;
+    title: string;
+    description: string;
+    from_price: number;
+    estimated_time?: string;
+    difficulty_level?: string;
+    bundle_discount_percentage?: number;
+    carfixValueProducts?: string[];
+    preparedTiers?: PreparedTier[];
+    icon_url?: string;
+}
+interface ServicePackageDetailViewProps {
+    package: ServicePackageDetail;
+    onBack: () => void;
+    onAddToCart?: (products: PreparedTierProduct[]) => void;
+    onNavigateToProductPage?: (sku: string) => void;
+}
+/**
+ * ServicePackageDetailView - CARFIX Website Specification
+ * Uses preparedTiers EXCLUSIVELY - no client-side fallback processing
+ * Server is the single source of truth for products, prices, and tiers
+ */
+export declare const ServicePackageDetailView: React.FC<ServicePackageDetailViewProps>;
+export {};

package/dist/components/mobile/index.d.ts

@@ -1,7 +1,9 @@
 export { MobileBobCharacter } from './MobileBobCharacter';
+export { MobileBobLayoutCore } from './MobileBobLayoutCore';
 export { MobileChatDrawer } from './MobileChatDrawer';
 export { MobileProductColumn } from './MobileProductColumn';
 export { MobileBobLayout } from './MobileBobLayout';
 export { ContainedMobileBobLayout } from './ContainedMobileBobLayout';
 export { ContainedChatDrawer } from './ContainedChatDrawer';
 export { ProductDetailView } from './ProductDetailView';
+export { ServicePackageDetailView } from './ServicePackageDetailView';

package/dist/hooks/useBobAnimation.d.ts

@@ -1,7 +1,16 @@
 export type AnimationState = string;
-export declare const useBobAnimation: () => {
+interface UseBobAnimationOptions {
+    isSpeaking?: boolean;
+}
+/**
+ * Bob Animation Hook - v3.0 requestAnimationFrame Implementation
+ *
+ * FIXES: Animation acceleration bug caused by setInterval stacking
+ * SOLUTION: Single RAF loop with refs for mutable state
+ */
+export declare const useBobAnimation: (options?: UseBobAnimationOptions) => {
     animationState: string;
-    setAnimationState: import('react').Dispatch<import('react').SetStateAction<string>>;
+    setAnimationState: (newState: AnimationState) => void;
     getCurrentImage: () => string;
     getCurrentOffset: () => number;
     getCurrentScale: () => number;
@@ -12,3 +21,4 @@ export declare const useBobAnimation: () => {
     setManualMode: import('react').Dispatch<import('react').SetStateAction<boolean>>;
     isLoading: boolean;
 };
+export {};

package/dist/hooks/useBobAnimationData.d.ts

@@ -45,6 +45,7 @@ export interface BobAnimationData {
  * Centralized React Query hook for Bob's animation data.
  * Fetches once, caches for 30 seconds, deduplicates requests across components.
  * Includes realtime subscriptions for automatic updates.
+ * Gracefully degrades when used outside BobProvider.
  */
 export declare const useBobAnimationData: (lookId?: string | null) => import('@tanstack/react-query').UseQueryResult<BobAnimationData, Error>;
 /**

package/dist/hooks/useBobStateTransitions.d.ts

@@ -10,6 +10,8 @@ export declare const useBobStateTransitions: ({ states, setAnimationState, manua
     chatStage: ChatStage;
     initialize: () => void;
     onUserInput: () => void;
+    onSpeechStart: () => void;
+    onSpeechEnd: () => void;
     onStreamStart: () => void;
     onStreamComplete: () => void;
     onShowingProduct: () => void;

package/dist/hooks/usePositionFactors.d.ts

@@ -0,0 +1,28 @@
+import { ViewportSize } from './useViewportSize';
+
+/**
+ * Position factors for responsive Bob positioning and UI scaling.
+ * These factors allow fine-tuned control across mobile, tablet, and desktop.
+ */
+export interface PositionFactors {
+    /** Multiplier for Bob's position offsets (1.0 = full offset, 0.5 = half) */
+    bobOffset: number;
+    /** Multiplier for product column width (1.0 = 80%, 0.6 = 48%) */
+    productWidth: number;
+    /** General UI element scaling factor */
+    uiScale: number;
+    /** Bob's partial-left position (percentage from left edge) */
+    partialLeftPosition: number;
+    /** Bob's hidden position (percentage from left edge) */
+    hiddenPosition: number;
+}
+/**
+ * Returns device-specific position factors for consistent Bob positioning
+ * across mobile, tablet, and desktop viewports.
+ */
+export declare function usePositionFactors(): PositionFactors;
+/**
+ * Get position factors for a specific viewport size.
+ * Can be used directly if viewport is known.
+ */
+export declare function getPositionFactors(viewport: ViewportSize): PositionFactors;

package/dist/hooks/useReturningUser.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Hook to detect returning users within a configurable time window.
+ * Stores last visit timestamp in localStorage and checks if user
+ * has visited within the threshold period.
+ */
+export declare function useReturningUser(thresholdDays?: number): {
+    isReturningUser: boolean;
+    lastVisitDate: Date | null;
+    daysSinceLastVisit: number | null;
+};

package/dist/hooks/useSparkDeals.d.ts

@@ -0,0 +1,27 @@
+export interface SparkDeal {
+    id: string;
+    brand: string;
+    product_name: string;
+    price: number;
+    original_price?: number;
+    image_url?: string;
+    sku: string;
+    category?: string;
+    valid_until?: string;
+}
+interface SparkDealsSettings {
+    enabled: boolean;
+    inRain: boolean;
+    rainFrequency: number;
+    primingEnabled: boolean;
+    bannerEnabled: boolean;
+    delayMs: number;
+    scrollSpeed: number;
+    maxPerSession: number;
+    minResearchTime: number;
+    bobCommentary: boolean;
+}
+export declare function useSparkDealsSettings(): import('@tanstack/react-query').UseQueryResult<SparkDealsSettings, Error>;
+export declare function useSparkDeals(enabled?: boolean): import('@tanstack/react-query').UseQueryResult<SparkDeal[], Error>;
+export declare function getSparkDealWords(deals: SparkDeal[]): string[];
+export {};

package/dist/hooks/useSpeechSynthesis.d.ts

@@ -4,11 +4,12 @@ interface UseSpeechSynthesisProps {
     onFailed?: () => void;
 }
 export declare const useSpeechSynthesis: ({ onStart, onEnd, onFailed, }?: UseSpeechSynthesisProps) => {
-    speak: (text: string) => Promise<void>;
+    speak: (text: string, isGreeting?: boolean) => void;
     stop: () => void;
     pause: () => void;
     resume: () => void;
     isSpeaking: boolean;
     isSupported: boolean;
+    retryPendingGreeting: () => void;
 };
 export {};

package/dist/hooks/useThemeSettings.d.ts

@@ -0,0 +1,22 @@
+export interface ThemeSetting {
+    id: string;
+    setting_key: string;
+    color_value: string;
+    hex_preview: string | null;
+    description: string | null;
+}
+export interface MatrixTheme {
+    primary: string;
+    secondary: string;
+    success: string;
+    background: string;
+    backgroundMode: 'dark' | 'light';
+    sparkDealColor: string;
+    primaryHex: string;
+    secondaryHex: string;
+    successHex: string;
+    backgroundHex: string;
+    sparkDealHex: string;
+}
+export declare function useThemeSettings(): import('@tanstack/react-query').UseQueryResult<MatrixTheme, Error>;
+export declare function getThemeCssVars(theme: MatrixTheme): Record<string, string>;

package/dist/hooks/useViewportSize.d.ts

@@ -0,0 +1,2 @@
+export type ViewportSize = 'mobile' | 'tablet' | 'desktop';
+export declare function useViewportSize(): ViewportSize;

package/dist/index.d.ts

@@ -3,19 +3,28 @@
  *
  * AI-powered automotive parts assistant widget - Full immersive experience
  *
+ * v3.0.0 - Major rebuild with multi-tenant support, RAF animations, swipeable Bob
  * v1.4.0 - Redesigned PTT button: 3x larger, green "TALK" text, floating cartoon style
  * v1.3.1 - Bottom offset support for host navigation bars
  * v1.3.0 - GA4 Analytics integration
  */
 export { BOB_VERSION, getBobVersion } from './version';
-export { BobProvider, useBobContext, useBobSupabase, useHostContext, useHostApiConfig, useBobCallbacks, useBobAnalyticsConfig, useBobAnalytics, useBobLayoutConfig, } from './BobProvider';
+export { BobProvider, useBobContext, useBobSupabase, useBobSupabaseSafe, useHostContext, useHostApiConfig, useBobCallbacks, useBobAnalyticsConfig, useBobAnalytics, useBobLayoutConfig, } from './BobProvider';
 export { BobWidget } from './components/BobWidget';
 export type { BobWidgetProps } from './components/BobWidget';
 export { Bob } from './components/Bob';
 export type { BobVariant } from './components/Bob';
 export { BobCharacter } from './components/BobCharacter';
 export { ChatInterface } from './components/ChatInterface';
-export { MobileBobCharacter, MobileChatDrawer, MobileProductColumn, MobileBobLayout, ContainedMobileBobLayout, ContainedChatDrawer } from './components/mobile';
+export { BobSuggestions } from './components/BobSuggestions';
+export { ProductBadge } from './components/ProductBadge';
+export { CARFIX_COLORS, QUALITY_TIER_CONFIG, IMAGE_URLS, BADGE_CONFIG, TYPOGRAPHY, isRotorProduct, getDisplayPrice, formatNZD, } from './styles/carfix-tokens';
+export { SwipeableBob } from './components/SwipeableBob';
+export { ProductTile } from './components/ProductTile';
+export { MatrixProductLoader } from './components/MatrixProductLoader';
+export type { LoaderPhase } from './components/MatrixProductLoader';
+export { SparkDealBanner } from './components/SparkDealBanner';
+export { MobileBobCharacter, MobileChatDrawer, MobileProductColumn, MobileBobLayout, MobileBobLayoutCore, ContainedMobileBobLayout, ContainedChatDrawer, ServicePackageDetailView } from './components/mobile';
 export { useBobChat } from './hooks/useBobChat';
 export { useSpeechSynthesis } from './hooks/useSpeechSynthesis';
 export { useBobAnimation } from './hooks/useBobAnimation';
@@ -23,9 +32,12 @@ export { useBobAnimationData } from './hooks/useBobAnimationData';
 export { useBobStateTransitions } from './hooks/useBobStateTransitions';
 export { useSpeechRecognition } from './hooks/useSpeechRecognition';
 export { useBobBackdrop } from './hooks/useBobBackdrop';
+export { useThemeSettings } from './hooks/useThemeSettings';
+export { useSparkDeals } from './hooks/useSparkDeals';
+export { useReturningUser } from './hooks/useReturningUser';
 export type { HostContext, HostUserContext, HostVehicleContext, HostCartContext, HostHistoryContext, BobConfig, HostApiConfig, BobCallbacks, BobProviderConfig, BobLayoutConfig, } from './types/context';
 export type { Vehicle } from './types/vehicle';
-export type { Product, APIPart, CartItem, ServicePackage, } from './types/product';
+export type { Product, APIPart, CartItem, ServicePackage, Partslot, QualityTiers, Part, } from './types/product';
 export type { Message, HighlightedProduct, } from './types/message';
 export type { BobAnimationConfig, AnimationStateDefinition, BobLook, BobAnimationData, } from './hooks/useBobAnimationData';
 export type { BobEventName, BobAnalyticsEvent, BobGA4Config, SessionStartParams, MessageSentParams, VehicleIdentifiedParams, PartsViewedParams, ProductParams, CheckoutParams, SpeechParams, ErrorParams, } from './types/analytics';