@bbearai/react-native 0.3.7 → 0.3.9

package/README.md

@@ -34,6 +34,7 @@ function App() {
         getCurrentUser: async () => ({
           id: user.id,
           email: user.email,
+          name: user.name, // Optional, shown on reports
         }),
       }}
     >
@@ -44,6 +45,138 @@ function App() {
 }
 ```
 
+## Configuration Options
+
+```tsx
+<BugBearProvider
+  config={{
+    // Required
+    projectId: 'your-project-id',
+    getCurrentUser: async () => ({ id: user.id, email: user.email }),
+
+    // Optional — rich context for bug reports
+    getAppContext: () => ({
+      currentRoute: currentScreenName,           // Current screen name
+      userRole: currentUser?.role,                // 'owner', 'manager', 'guest', etc.
+      propertyId: selectedProperty?.id,           // App-specific context
+      custom: { theme: 'dark' },                 // Any additional data
+    }),
+
+    // Optional — callbacks
+    dashboardUrl: 'https://app.bugbear.ai',              // Web dashboard link in widget
+    onNavigate: (route) => navigation.navigate(route),   // Deep link handler for test cases
+    onReportSubmitted: (report) => { ... },               // After report submission
+    getNavigationHistory: () => [...recentScreens],       // Custom nav tracking
+
+    // Optional — self-hosted
+    supabaseUrl: '...',
+    supabaseAnonKey: '...',
+  }}
+  enabled={isAuthReady} // Delay init until auth is ready (default: true)
+>
+```
+
+### Why use `getAppContext`?
+
+When a tester reports a bug, BugBear attaches the app context to the report. This tells the developer fixing the bug:
+- **Which screen** the bug is on
+- **What role** the user has (critical for role-dependent bugs)
+- **App-specific state** like selected property, active filters, etc.
+
+The bug report form also includes a **"Which screen?"** field so testers can specify the affected screen manually.
+
+## Automatic Context Capture
+
+BugBearProvider automatically captures debugging context with zero configuration:
+
+| Data | Details |
+|------|---------|
+| **Console logs** | Last 50 `console.log/warn/error/info` calls |
+| **Network requests** | Last 20 `fetch()` calls with method, URL, status, duration |
+| **Failed response bodies** | First 500 chars of 4xx/5xx response bodies |
+| **Performance** | Page load time, memory usage |
+| **Environment** | Language, timezone, online status |
+
+This data is attached to every bug report and available to the MCP server's `get_report_context` tool for AI-assisted debugging.
+
+> **Note:** For React Native, navigation history is not auto-captured (no `pushState`). Use `getNavigationHistory` or React Navigation integration below for screen tracking.
+
+## Navigation Tracking
+
+### React Navigation integration
+
+```tsx
+import { useNavigationContainerRef } from '@react-navigation/native';
+
+function App() {
+  const navigationRef = useNavigationContainerRef();
+  const routeHistory = useRef<string[]>([]);
+
+  return (
+    <BugBearProvider
+      config={{
+        projectId: 'your-project-id',
+        getCurrentUser: async () => ({ id: user.id, email: user.email }),
+        getNavigationHistory: () => routeHistory.current,
+        getAppContext: () => ({
+          currentRoute: navigationRef.getCurrentRoute()?.name || 'unknown',
+          userRole: currentUser?.role,
+        }),
+      }}
+    >
+      <NavigationContainer
+        ref={navigationRef}
+        onStateChange={() => {
+          const name = navigationRef.getCurrentRoute()?.name;
+          if (name) {
+            routeHistory.current.push(name);
+            // Keep last 20
+            if (routeHistory.current.length > 20) routeHistory.current.shift();
+          }
+        }}
+      >
+        {/* Your navigation */}
+      </NavigationContainer>
+      <BugBearButton />
+    </BugBearProvider>
+  );
+}
+```
+
+## Widget Architecture
+
+The widget uses a navigation stack pattern with 10 screens:
+
+| Screen | Purpose |
+|--------|---------|
+| **Home** | Smart hero banner + 2x2 action grid + progress bar + web dashboard link |
+| **Test Detail** | One-test-at-a-time execution with pass/fail/skip actions |
+| **Test List** | All assignments grouped by folder with filter bar |
+| **Test Feedback** | Star rating + quality flags after pass/fail |
+| **Report** | Bug/feedback submission with type, severity, description, affected screen |
+| **Report Success** | Confirmation with auto-return to home |
+| **Message List** | Thread list with unread badges + compose button |
+| **Thread Detail** | Chat bubbles + reply composer |
+| **Compose Message** | New thread form with subject + message |
+| **Profile** | Tester info, stats, and editable fields |
+
+## Button Configuration
+
+The BugBear button is draggable by default with edge-snapping behavior:
+
+```tsx
+<BugBearButton
+  draggable={true}           // Enable/disable dragging (default: true)
+  position="bottom-right"    // Initial position: 'bottom-right' | 'bottom-left'
+  initialX={100}             // Custom initial X position (optional)
+  initialY={500}             // Custom initial Y position (optional)
+  minY={100}                 // Minimum Y from top (default: 100)
+  maxYOffset={160}           // Max Y offset from bottom (default: 160)
+/>
+```
+
+The button automatically snaps to the nearest screen edge when released.
+
 ## Monorepo Setup
 
 When using BugBear in a monorepo (e.g., with Turborepo, Nx, or Yarn Workspaces), you may encounter React duplicate instance errors like:
@@ -105,90 +238,6 @@ If you're using Yarn workspaces, you can also configure hoisting to ensure a sin
 }
 ```
 
-## Configuration Options
-
-```tsx
-<BugBearProvider
-  config={{
-    projectId: 'your-project-id',           // Required: Your BugBear project ID
-    getCurrentUser: async () => {...},       // Required: Return current user info
-    dashboardUrl: 'https://app.bugbear.ai', // Optional: Web dashboard link in widget
-    getNavigationHistory: () => [...],       // Optional: Custom navigation tracking
-    onNavigate: (route) => {...},            // Optional: Deep link handler for test cases
-    onReportSubmitted: (report) => {...},    // Optional: Callback after report submission
-  }}
->
-```
-
-## Widget Architecture
-
-The widget uses a navigation stack pattern with 10 screens:
-
-| Screen | Purpose |
-|--------|---------|
-| **Home** | Smart hero banner + 2x2 action grid + progress bar + web dashboard link |
-| **Test Detail** | One-test-at-a-time execution with pass/fail/skip actions |
-| **Test List** | All assignments grouped by folder with filter bar |
-| **Test Feedback** | Star rating + quality flags after pass/fail |
-| **Report** | Bug/feedback submission with type, severity, description |
-| **Report Success** | Confirmation with auto-return to home |
-| **Message List** | Thread list with unread badges + compose button |
-| **Thread Detail** | Chat bubbles + reply composer |
-| **Compose Message** | New thread form with subject + message |
-| **Profile** | Tester info, stats, and editable fields |
-
-## Navigation Tracking
-
-BugBear can automatically track navigation history for better bug context. If you're using React Navigation:
-
-```tsx
-import { useNavigationContainerRef } from '@react-navigation/native';
-
-function App() {
-  const navigationRef = useNavigationContainerRef();
-  const routeNameRef = useRef<string>();
-
-  return (
-    <BugBearProvider
-      projectId="your-project-id"
-      getCurrentUser={...}
-      getNavigationHistory={() => routeNameRef.current ? [routeNameRef.current] : []}
-    >
-      <NavigationContainer
-        ref={navigationRef}
-        onReady={() => {
-          routeNameRef.current = navigationRef.getCurrentRoute()?.name;
-        }}
-        onStateChange={() => {
-          const currentRouteName = navigationRef.getCurrentRoute()?.name;
-          routeNameRef.current = currentRouteName;
-        }}
-      >
-        {/* Your navigation */}
-      </NavigationContainer>
-      <BugBearWidget />
-    </BugBearProvider>
-  );
-}
-```
-
-## Button Configuration
-
-The BugBear button is draggable by default with edge-snapping behavior:
-
-```tsx
-<BugBearButton
-  draggable={true}           // Enable/disable dragging (default: true)
-  position="bottom-right"    // Initial position: 'bottom-right' | 'bottom-left'
-  initialX={100}             // Custom initial X position (optional)
-  initialY={500}             // Custom initial Y position (optional)
-  minY={100}                 // Minimum Y from top (default: 100)
-  maxYOffset={160}           // Max Y offset from bottom (default: 160)
-/>
-```
-
-The button automatically snaps to the nearest screen edge when released.
-
 ## Troubleshooting
 
 ### Widget not showing
@@ -203,10 +252,12 @@ If you're using your own Supabase instance, provide the credentials:
 
 ```tsx
 <BugBearProvider
-  projectId="your-project-id"
-  supabaseUrl="https://your-instance.supabase.co"
-  supabaseAnonKey="your-anon-key"
-  getCurrentUser={...}
+  config={{
+    projectId: 'your-project-id',
+    supabaseUrl: 'https://your-instance.supabase.co',
+    supabaseAnonKey: 'your-anon-key',
+    getCurrentUser: async () => ({ id: user.id, email: user.email }),
+  }}
 >
 ```
 
@@ -216,15 +267,11 @@ If you're using your own Supabase instance, provide the credentials:
 
 The BugBear button renders within the normal React Native view hierarchy using absolute positioning. When your app displays modals, bottom sheets, or the keyboard, the button may be hidden behind them.
 
-This is a platform limitation - React Native doesn't provide a built-in way to render views above all modals without using a Modal component (which would block touch events on the underlying app).
-
 **Workarounds:**
 - Accept that the button won't be accessible when modals are open
 - Consider dismissing the modal to access BugBear
 - For testing flows that involve modals, provide an alternative way to trigger the BugBear widget
 
-We're investigating solutions using `react-native-portal` or similar libraries for future releases.
-
 ## License
 
 MIT