@gymmymac/bob-widget 3.2.3 → 3.2.5

package/BOB-DOCUMENTATION.md

@@ -1,11 +1,22 @@
 # Bob Widget - Complete Documentation
 
-> **Version:** 3.1.19 | **Last Updated:** February 2026
+> **Version:** 3.2.1 | **Last Updated:** February 2026
 
 AI-powered automotive parts assistant widget for seamless integration into partner websites.
 
 ---
 
+## 📖 Documentation Map
+
+| Document | What It Covers |
+|----------|---------------|
+| **This file** | Technical reference: props, API, CSS, troubleshooting, 3-stage install |
+| **[README.md](./README.md)** | Quick start, installation, container setup, callbacks |
+| **[CHANGELOG.md](./CHANGELOG.md)** | Version history |
+| **[BOB-COMPLETE-PROCESS-FLOW.md](../../BOB-COMPLETE-PROCESS-FLOW.md)** (project root) | Bob's personality, conversation states, Brain diagnostics, canned speech, customer playbook |
+
+---
+
 ## Table of Contents
 
 1. [Overview](#1-overview)
@@ -14,11 +25,10 @@ AI-powered automotive parts assistant widget for seamless integration into partn
 4. [Props Reference](#4-props-reference)
 5. [Session Handoff](#5-session-handoff)
 6. [CSS Customization](#6-css-customization)
-7. [Bob's Behaviour Guidelines](#7-bobs-behaviour-guidelines)
+7. [Bob's Personality & Behaviour](#7-bobs-personality--behaviour)
 8. [API Reference](#8-api-reference)
 9. [Troubleshooting](#9-troubleshooting)
 10. [CARFIX 3-Stage Installation](#10-carfix-3-stage-installation)
-11. [Changelog Summary](#11-changelog-summary)
 
 ---
 
@@ -394,74 +404,11 @@ This prevents host site styles from bleeding into Bob and vice versa.
 
 ---
 
-## 7. Bob's Behaviour Guidelines
-
-### Personality & Voice
-
-Bob is a friendly, knowledgeable Kiwi auto parts expert with a relaxed, helpful tone.
-
-| Expression | Meaning | When to Use |
-|------------|---------|-------------|
-| "Sweet as" | All good, perfect | Confirming something |
-| "Mate" | Friendly address | Throughout conversation |
-| "Choice" | Excellent | When something is good |
-| "Chur" | Thanks/Cool | Quick acknowledgment |
-| "She'll be right" | It'll be fine | Reassurance |
-| "Yeah nah" | No | Gentle decline |
-| "Away laughing" | Sorted, good to go | After solving a problem |
+## 7. Bob's Personality & Behaviour
 
-### Response Length Guidelines
-
-| Situation | Response Style |
-|-----------|----------------|
-| No vehicle identified yet | SHORT - 1-2 sentences max |
-| Vehicle confirmed | Can be slightly longer |
-| Product recommendation | 2-3 sentences + point to shelf |
-| Checkout/cart | Brief confirmation |
-
-### Vehicle Identification Workflow
-
-1. **REGO (License Plate)** - Primary identifier, gives exact match
-2. **Make + Model + Year + Engine CC** - Fallback when no REGO
-
-```
-First ask: "What's your rego, mate?"
-If no rego: "No worries - what make, model, and year is she?"
-If needed: "What's the engine size? 1.8L, 2.0L...?"
-```
-
-### Product Recommendations - Golden Rules
-
-1. **NEVER recommend cheapest first** - Lowest margin, lowest quality
-2. **Lead with mid-priced "best value"** option
-3. **Max 2-3 products mentioned verbally** - Let the shelf show the rest
-4. **ONLY recommend products from retrieve_parts results** - Never hallucinate brands
-
-### Cart & Checkout Rules (CRITICAL)
-
-- **NEVER add to cart** unless customer explicitly says:
-  - "add to cart", "I'll take it", "buy it", "yes please"
-- If customer says "that one" or "the first one", **confirm WHICH product** before adding
-- **NEVER claim to add products without calling add_to_cart tool**
-
-### Things Bob NEVER Does
-
-| Never Do | Why |
-|----------|-----|
-| Offer to fit parts | CARFIX only sells parts - DIY or workshop fitment |
-| Mention stock status | All displayed parts are in stock |
-| List more than 3 products verbally | Let the shelf do the work |
-| Recommend cheapest option first | Low margin, low quality perception |
-| Hallucinate brands or products | Only recommend from actual tool results |
-| Add to cart without explicit request | Customer must say "add", "buy", "take it" |
-
-### Anti-Hallucination Rules
-
-1. **ONLY mention products that appear in tool responses**
-2. If no tool returned products, **DO NOT invent alternatives**
-3. If search fails or returns empty, say: "I don't have that in my system right now"
-4. **NEVER recommend brands, SKUs, or prices** not retrieved from tools
-5. **NEVER fabricate product names** like "Best Value wipers"
+> **Full reference moved →** See **[BOB-COMPLETE-PROCESS-FLOW.md](../../BOB-COMPLETE-PROCESS-FLOW.md)** for Bob's complete personality guide, conversation states, Brain diagnostics, canned speech triggers, and customer interaction playbook.
+>
+> This section previously duplicated that content. The master document is now the single source of truth for all behavioural guidelines.
 
 ---
 
@@ -605,9 +552,6 @@ After installation, you can find the scripts in:
 ```
 node_modules/@gymmymac/bob-widget/
 ├── bin/bob-widget.mjs           # CLI entrypoint
-├── install/carfix/
-│   ├── 00-README-PREINSTALL.md  # This guide
-│   └── 05-runtime-verification-checklist.md
 ├── BOB-DOCUMENTATION.md         # Full documentation
 └── CHANGELOG.md                 # Version history
 ```
@@ -983,67 +927,6 @@ export default function AskBobPage() {
 
 ---
 
-## 11. Changelog Summary
-
-### v3.1.9 (Current)
-- 🔧 **3-Stage Installation Process**: Complete rewrite of Section 10 with strict sequential stages
-  - **Stage A: Forensic Removal** - Script now EXITS with error if any Bob files/imports found
-  - **Stage B: Page Preparation** - Clear template for creating blank container page
-  - **Stage C: Install & Verify** - Fresh installation with mandatory verification checklist
-- 📖 **Documentation Restructure**: Installation and cleanup clearly separated into distinct stages
-- ⚠️ **Prevents Legacy Code Interference**: Enhanced cleanup script with comprehensive detection
-
-### v3.1.8
-- 📖 **Documentation Clarity**: Clarified that Bob container is placed on a page WITH existing CARFIX header/bottom nav
-- ⚠️ **Pre-Install Requirements**: Emphasized mandatory forensic cleanup before installation
-- 📐 **Page Layout Context**: Added explicit guidance that Bob fits BETWEEN fixed layout elements
-
-### v3.1.7
-- 📦 **Version Sync**: Prepared release with all version references aligned
-
-### v3.1.6
-- 📖 **README Update**: Added prominent "Read Before Installing" section
-- 📐 **Layout Corrections**: Documented 144px offset formula with safe-area support
-
-### v3.1.5
-- 📦 **Version Sync**: Re-released to sync package.json version with GitHub release tag
-- 📐 **Layout Corrections**: Updated CARFIX measurements to 72px header + 72px bottom nav
-
-### v3.1.4
-- 📦 **Supabase Bundling**: Removed @supabase/supabase-js from external to prevent "module not found" errors
-- 🔒 **HTTPS Validation**: Added programmatic check for PTT - warns users on HTTP connections
-- 🔧 **Debug Logging**: Consolidated all internal logs via bobLog utility respecting debug prop
-
-### v3.1.3
-- 🎨 **CSS Isolation**: Enhanced with `isolation: isolate` and `all: initial`
-- 📐 **Embedded Mode**: Added `embedded` prop for fullscreen variant in host containers
-
-### v3.1.2
-- 🔊 **Pre-recorded Audio Clips**: Fixed context property mismatch where `useSpeechSynthesis` was accessing `supabase` instead of `bobSupabase`, causing pre-recorded clips to never play
-
-### v3.1.1
-- ⚛️ **React Hooks Order Violation**: Fixed hooks being called after conditional returns
-- 🌐 **Allowed Origins**: Added Lovable preview domain support
-
-### v3.1.0
-- 🎯 **BobStandalone**: Auto-configures from database - 4 lines to integrate
-- 🗄️ **Partner Config System**: All settings in `bob_partners` table
-- 🎨 **CSS Variables**: Customizable blur, opacity, colors
-- 🔍 **Debug Overlay**: Visual diagnostic tool
-- 📦 **Simplified Callbacks**: Only essential callbacks required
-
-### v3.0.x
-- 🎭 **SwipeableBob**: Gesture-based interactions
-- 🏢 **Multi-Tenant Support**: Configurable looks and animations per tenant
-- 🎬 **RAF Animations**: Smooth 60fps animations
-- ⚡ **MatrixProductLoader**: Cyberpunk-style loading
-- 🔥 **SparkDealBanner**: Animated promotional banners
-- 👋 **Returning User Detection**: Personalized greetings
-
-See [CHANGELOG.md](./CHANGELOG.md) for full version history.
-
----
-
 ## Dependencies
 
 Bob Widget v3.1.9 **bundles** its own dependencies. Your project only needs:

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to the `@gymmymac/bob-widget` package will be documented in
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [v3.2.5] - 2026-03-09
+
+### Fixed
+- 🔇 **Bug #1 — Quick-Reply Speech Stop**: Quick-reply/suggestion buttons now call `onInterrupt()` to stop all active speech before triggering `onNavigate`, preventing jarring audio overlap during navigation
+- 🎛️ **Bug #2 — Imperative Stop Handle**: `BobStandaloneHandle.stopSpeech()` / `.interrupt()` now calls `stopAllAudio` (TTS + canned clips + searching audio) instead of only cancelling TTS — host apps can now fully silence Bob via ref
+- 🎤 **Bug #3 — PTT Interrupt During Canned Audio**: Composite `isSpeaking` state now tracks both TTS and audio controller playback, so the PTT button correctly detects the `speaking` state during pre-recorded clips and interrupts immediately on tap
+
+---
+
+## [v3.2.4] - 2026-03-09
+
+### Fixed
+- 🛒 **Service Package Add-to-Cart**: Fixed `onAddToCart` callback receiving `undefined` fields when adding a service package tier — handler now correctly unwraps `Product[]` arrays passed by `MobileProductColumn`, iterating each item individually so all fields (`product_id`, `product_name`, `sku`, `unit_price`, `brand`, `image_url`) are populated correctly
+
+---
+
 ## [v3.2.3] - 2026-02-16
 
 ### Fixed

package/README.md

@@ -6,6 +6,17 @@ AI-powered automotive parts assistant widget for partner websites.
 
 ---
 
+## 📖 Documentation Map
+
+| Document | What It Covers |
+|----------|---------------|
+| **This README** | Quick start, installation, container setup, callbacks |
+| **[BOB-DOCUMENTATION.md](./BOB-DOCUMENTATION.md)** | Full technical reference, props, troubleshooting, 3-stage install |
+| **[CHANGELOG.md](./CHANGELOG.md)** | Version history |
+| **[BOB-COMPLETE-PROCESS-FLOW.md](../../BOB-COMPLETE-PROCESS-FLOW.md)** (project root) | Bob's personality, conversation states, Brain diagnostics, canned speech, customer playbook |
+
+---
+
 ## 🚨 STOP — RUN THE INSTALLER FIRST
 
 Bob v3.1.19 includes an **executable 3-stage installer**. Do NOT skip this step.
@@ -458,14 +469,6 @@ Run locally: `cd packages/bob-widget && npx vitest run`
 
 ---
 
-## 📖 Additional Documentation
-
-| Document | Description |
-|----------|-------------|
-| **[BOB-DOCUMENTATION.md](./BOB-DOCUMENTATION.md)** | Complete integration guide with troubleshooting |
-| **[CHANGELOG.md](./CHANGELOG.md)** | Version history and release notes |
-| **[install/carfix/](./install/carfix/)** | Installer scripts, templates, and verification checklists |
-
 ---
 
 ## Support

package/dist/__tests__/bobV2DirectorModes.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Bob V2.0 Director Mode Tests
+ *
+ * Validates the three selling modes (Helper, Consultant, Gatekeeper)
+ * and Vehicle Awareness protocol introduced in V2.0.
+ *
+ * These tests call the bob-chat edge function directly and assert on
+ * the SSE response content and structure.
+ */
+export {};

package/dist/__tests__/quickReplyAndStopSpeech.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Quick-Reply Navigation + Imperative stopSpeech Tests
+ *
+ * Covers:
+ *   1. QuickReply type shape & Message.quickReplies field
+ *   2. navigate_url SSE event handling logic
+ *   3. quick_replies SSE event attaches buttons to last assistant message
+ *   4. BobStandaloneHandle interface contract
+ *   5. onStopSpeechReady capture pattern
+ */
+export {};

package/dist/__tests__/v325BugFixes.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * v3.2.5 Bug Fix Regression Tests
+ *
+ * Covers three critical CARFIX production bugs:
+ *   Bug #1 — Quick-reply buttons must call onInterrupt before onQuickReply (stop speech before navigating)
+ *   Bug #2 — Imperative handle must call stopAllAudio (TTS + canned + searching), not just stopSpeech
+ *   Bug #3 — Composite isSpeaking must be true when EITHER TTS or audio controller is playing
+ */
+export {};

package/dist/components/BobStandalone.d.ts

@@ -1,11 +1,28 @@
 import { default as React } from 'react';
 import { StandaloneWidgetProps } from '../types/partner';
 
+/**
+ * Imperative handle exposed via ref on BobStandalone.
+ * Allows hosts to programmatically stop speech, e.g. when navigating away.
+ *
+ * @example
+ * ```tsx
+ * const bobRef = useRef<BobStandaloneHandle>(null);
+ * bobRef.current?.stopSpeech();
+ * <BobStandalone ref={bobRef} partner="CARFIX" ... />
+ * ```
+ */
+export interface BobStandaloneHandle {
+    /** Stop any active speech (TTS or canned audio) immediately */
+    stopSpeech: () => void;
+    /** Alias for stopSpeech - interrupts Bob mid-sentence */
+    interrupt: () => void;
+}
 /**
  * BobStandalone - Simplified partner integration component
  *
  * Reduces integration from 30+ lines to just 4 lines of code.
  * All configuration is auto-loaded from the bob_partners database table.
  */
-export declare const BobStandalone: React.FC<StandaloneWidgetProps>;
+export declare const BobStandalone: React.ForwardRefExoticComponent<StandaloneWidgetProps & React.RefAttributes<BobStandaloneHandle>>;
 export default BobStandalone;

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

@@ -14,8 +14,12 @@ interface ContainedChatDrawerProps {
     isMuted?: boolean;
     onToggleMute?: () => void;
     isSpeaking?: boolean;
+    /** Called when a quick-reply CTA button is tapped — fires onNavigate(url), no chat message sent */
+    onQuickReply?: (url: string) => void;
     /** Counter height as percentage of container - chat positions above this */
     counterHeightPercent?: number;
+    /** Called when PTT is tapped while Bob is speaking — immediately stops audio */
+    onInterrupt?: () => void;
 }
 /**
  * ContainedChatDrawer - Premium Glassmorphism Chat Drawer

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

@@ -31,6 +31,10 @@ interface ContainedMobileBobLayoutProps {
     isResearching?: boolean;
     onAddToCart?: (product: Product) => void;
     onNavigateToProductPage?: (product: Product) => void;
+    /** Called when a quick-reply CTA button is tapped — fires onNavigate(url), no chat message sent */
+    onQuickReply?: (url: string) => void;
+    /** Called when PTT is tapped while Bob is speaking — immediately stops audio */
+    onInterrupt?: () => void;
     vehicle?: Vehicle | null;
     onChangeVehicle?: () => void;
     pendingVariants?: VariantCard[];

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

@@ -31,6 +31,10 @@ interface MobileBobLayoutProps {
     isResearching?: boolean;
     onAddToCart?: (product: Product) => void;
     onNavigateToProductPage?: (product: Product) => void;
+    /** Called when a quick-reply CTA button is tapped — fires onNavigate(url), no chat message sent */
+    onQuickReply?: (url: string) => void;
+    /** Called when PTT is tapped while Bob is speaking — immediately stops audio */
+    onInterrupt?: () => void;
     vehicle?: Vehicle | null;
     onChangeVehicle?: () => void;
     pendingVariants?: VariantCard[];

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

@@ -17,8 +17,12 @@ interface MobileChatDrawerProps {
     isSpeaking?: boolean;
     onAddToCart?: (product: Product) => void;
     onProductClick?: (product: Product) => void;
+    /** Called when a quick-reply CTA button is tapped — fires onNavigate(url), no chat message sent */
+    onQuickReply?: (url: string) => void;
     /** Counter height as percentage of container - chat positions above this */
     counterHeightPercent?: number;
+    /** Called when PTT is tapped while Bob is speaking — immediately stops audio */
+    onInterrupt?: () => void;
 }
 export declare const MobileChatDrawer: React.FC<MobileChatDrawerProps>;
 export {};

package/dist/hooks/useBobAnalytics.d.ts

@@ -16,6 +16,10 @@ interface UseBobAnalyticsProps {
     callbacks?: BobCallbacks;
     /** Whether analytics is enabled */
     enabled?: boolean;
+    /** Bob Supabase URL for conversation tracking */
+    bobSupabaseUrl?: string;
+    /** Bob Supabase anon key for conversation tracking */
+    bobSupabaseKey?: string;
 }
 interface UseBobAnalyticsReturn {
     /** Track any event */
@@ -65,6 +69,13 @@ interface UseBobAnalyticsReturn {
     trackSpeechFailed: (textLength: number) => void;
     /** Track error */
     trackError: (errorType: string, errorMessage: string) => void;
+    /** Track conversation activity (upsert to bob_conversations) */
+    trackConversationActivity: (extras?: {
+        had_product_match?: boolean;
+        led_to_cart?: boolean;
+        vehicle_id?: string;
+        rego?: string;
+    }) => void;
 }
 /**
  * Hook for tracking Bob widget analytics events
@@ -73,5 +84,5 @@ interface UseBobAnalyticsReturn {
  * 1. GA4 via gtag() if configured and available
  * 2. onAnalyticsEvent callback for server-side storage
  */
-export declare function useBobAnalytics({ ga4Config, hostContext, callbacks, enabled, }: UseBobAnalyticsProps): UseBobAnalyticsReturn;
+export declare function useBobAnalytics({ ga4Config, hostContext, callbacks, enabled, bobSupabaseUrl, bobSupabaseKey, }: UseBobAnalyticsProps): UseBobAnalyticsReturn;
 export default useBobAnalytics;

package/dist/hooks/useBobChat.d.ts

@@ -39,5 +39,7 @@ export declare const useBobChat: ({ setAnimationState, manualMode, talkingState,
     isSpeaking: boolean;
     identifiedVehicle: Vehicle | null;
     clearVehicle: () => void;
+    sendDirectMessage: (content: string) => void;
+    stopAllAudio: () => void;
 };
 export {};

package/dist/hooks/useMicPermission.d.ts

@@ -0,0 +1,12 @@
+type MicPermissionState = 'prompt' | 'granted' | 'denied' | 'unsupported';
+/**
+ * Proactively requests microphone permission on mount so the browser dialog
+ * appears early (e.g. when Bob loads) rather than mid-conversation when the
+ * user first taps PTT.
+ *
+ * Once granted, the browser remembers the choice for the domain.
+ */
+export declare const useMicPermission: (requestEarly?: boolean) => {
+    micPermission: MicPermissionState;
+};
+export {};

package/dist/hooks/useSpeechSynthesis.d.ts

@@ -5,7 +5,7 @@ interface UseSpeechSynthesisProps {
 }
 export declare const useSpeechSynthesis: ({ onStart, onEnd, onFailed, }?: UseSpeechSynthesisProps) => {
     speak: (text: string, isGreeting?: boolean) => void;
-    stop: () => void;
+    stop: (suppressCallbacks?: boolean) => void;
     pause: () => void;
     resume: () => void;
     isSpeaking: boolean;

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export { BobProvider, useBobContext, useBobSupabase, useBobSupabaseSafe, useHost
 export { BobWidget } from './components/BobWidget';
 export type { BobWidgetProps } from './components/BobWidget';
 export { BobStandalone } from './components/BobStandalone';
+export type { BobStandaloneHandle } from './components/BobStandalone';
 export type { StandaloneWidgetProps } from './types/partner';
 export { usePartnerConfig, getFeatureFlag } from './hooks/usePartnerConfig';
 export type { PartnerConfig, PartnerFeatureFlags, EssentialCallbacks } from './types/partner';
@@ -37,6 +38,7 @@ export { useBobAnimation } from './hooks/useBobAnimation';
 export { useBobAnimationData } from './hooks/useBobAnimationData';
 export { useBobStateTransitions } from './hooks/useBobStateTransitions';
 export { useSpeechRecognition } from './hooks/useSpeechRecognition';
+export { useMicPermission } from './hooks/useMicPermission';
 export { useBobBackdrop } from './hooks/useBobBackdrop';
 export { useThemeSettings } from './hooks/useThemeSettings';
 export { useSparkDeals } from './hooks/useSparkDeals';
@@ -46,6 +48,6 @@ export type { BobHealthCheckResult } from './hooks/useBobHealthCheck';
 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, Partslot, QualityTiers, Part, } from './types/product';
-export type { Message, HighlightedProduct, } from './types/message';
+export type { Message, HighlightedProduct, QuickReply, } 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';