Buggerov embeds a floating action button into your web app that lets clients or testers highlight bugs directly on the screen, write a description, and export a clean report with full browser metadata and console logs.

Features

• 📸 On-screen Annotation: Highlight target bugs with simple drag-to-draw rectangle selectors.
• 💻 Console Log Interceptor: Automatically captures console logs (console.log, warn, error, info) with proper error stack serialization.
• 🚨 Global Exception Handling: Automatically captures unhandled exceptions and promise rejections.
• 🌐 Network Request Sniffer: Monitors failed fetch and XMLHttpRequest calls (status codes $\ge 400$ or network drops) and logs them.
• 🎨 Premium Aesthetic: Modern dark/light glassmorphic UI, responsive layouts, micro-animations, and a fullscreen screenshot lightbox.
• 📝 Markdown Export: Direct markdown clipboard copying and local .md downloads containing all metadata and inline screenshots.
• 🔗 Zero-config Webhooks: Automatically POSTs the structured report payload directly to any Slack, Discord, or custom webhook url.
• 📋 Session Reports Dashboard: An in-widget dashboard containing all captured bug reports. Testers can copy/download individual reports, toggle developer log details, zoom screenshots, or batch export/clear reports.
• 🔌 Offline / Webhook-free Mode: Run purely client-side! If no webhookUrl is provided, reports are accumulated in the session and can be manually exported by the tester.

Installation

Add Buggerov as a dependency to your project:

npm install buggerov

Quick Start

Import the library and call the initialization function in your entry file (e.g., main.ts or index.ts). Styles are bundled natively, so there is no need to import a separate stylesheet.

import { initBuggerov } from 'buggerov';

initBuggerov({
  webhookUrl: 'https://your-webhook-endpoint.com/api/feedback',
  enabled: true // Force enable (bypasses dev/staging environment checks)
});

How It Works (Auto-Enable Detection)

If the enabled field is not provided, Buggerov will auto-detect whether it should render based on the current context:

• Checks if the bundler indicates a non-production build (process.env.NODE_ENV !== 'production' or Vite's import.meta.env.DEV).
• Checks if the hostname is a local loopback address (localhost, 127.0.0.1, [::1], or .local).
• Checks if the hostname contains common QA/staging keywords (e.g., dev, stage, staging, qa, test, preview, beta, sandbox).

Session Reports Dashboard & Offline Mode

When Buggerov is initialized, it displays a dual-button Floating Action Button (FAB) container:

1. Report Bug Button (Left): Enters screenshot capture and annotation mode.
2. Dashboard Button (Right): Circular button with a numeric red badge showing the count of bugs captured in the current session.

Offline and Local Storage Persistence

Captured reports are persisted in sessionStorage. This ensures that even if a tester navigates to another page, submits a form, or reloads the browser tab, the accumulated list of reports is preserved.

In-Widget Dashboard Features

Clicking the dashboard button opens the glassmorphic Session Reports manager containing:

• Screenshot Lightbox: Click any screenshot thumbnail to open a fullscreen zoom overlay.
• Inline Logs Inspecting: Click the Logs button on any card to toggle a code view of the captured logs for that specific bug.
• Individual Operations: Copy markdown or download a .md file for any specific bug report.
• Batch Operations: Copy all reports as a single combined markdown document, export/download all reports as a combined .md file, or clear all reports from the session storage.

API Reference

initBuggerov(config: BuggerovConfig)

Initializes the visual feedback widget and returns the BuggerovWidget instance (or null if disabled).

BuggerovConfig Options

| Property | Type | Default | Description | | :--- | :--- | :--- | :--- | | webhookUrl | string | undefined | URL where the JSON report payload will be POSTed. | | enabled | boolean \| (() => boolean) | Auto-detected | Overrides dev/staging detection checks. | | buttonText | string | "Report Bug" | Text label displayed on the floating action button. | | buttonPosition | 'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' | 'bottom-right' | Position of the floating button on the screen. | | customMetadata | Record<string, any> \| (() => Record<string, any>) | undefined | Additional variables to include in the report metadata. | | theme | 'light' \| 'dark' \| 'auto' | 'auto' | Color scheme for the feedback widget UI. | | maxLogs | number | 50 | Maximum number of console logs to preserve. | | customHeaders | Record<string, string> | undefined | Custom headers sent with the webhook POST request. | | onSuccess | () => void | undefined | Callback triggered after a successful report submission. | | onError | (error: Error) => void | undefined | Callback triggered if the webhook request fails. |

Webhook Payload Structure

When feedback is submitted, Buggerov sends a POST request containing a JSON body of type BuggerovPayload:

{
  "screenshot": "data:image/png;base64,iVBORw0KGgo...",
  "note": "The submit button has a weird alignment issue on mobile.",
  "metadata": {
    "url": "http://localhost:3000/",
    "title": "Buggerov Demo",
    "timestamp": "2026-05-28T21:13:30.000Z",
    "viewportWidth": 1280,
    "viewportHeight": 720,
    "screenWidth": 1920,
    "screenHeight": 1080,
    "userAgent": "Mozilla/5.0 ...",
    "os": "Windows",
    "browser": "Chrome",
    "logs": [
      {
        "type": "info",
        "message": "User action tracked. Current epoch time: 1779999934904",
        "timestamp": "2026-05-28T21:13:28.000Z"
      },
      {
        "type": "error",
        "message": "[Unhandled Exception] Error: AuthException: session expired",
        "timestamp": "2026-05-28T21:13:29.000Z"
      }
    ],
    "custom": {}
  }
}