### Install and Configure Development Environment
Source: https://github.com/mean-weasel/bugdrop/blob/main/CONTRIBUTING.md
Clone the repository, install dependencies, configure environment variables, and start the development server.
```bash
git clone https://github.com/mean-weasel/bugdrop
cd bugdrop
make install
cp .dev.vars.example .dev.vars
# Edit .dev.vars with your GitHub App credentials
make dev
# Visit http://localhost:8787/test/
```
--------------------------------
### Full HTML Example with BugDrop
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/website/installation.mdx
An example of a complete HTML page structure with the BugDrop widget script included.
```html
My Website
```
--------------------------------
### Install WebKit and Run Smoke Test
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/plans/2026-05-15-merge-queue-cross-browser-preview.md
Commands to install WebKit with dependencies and then run Playwright smoke tests on WebKit against a preview deployment.
```bash
npx playwright install --with-deps webkit
LIVE_TARGET=preview PLAYWRIGHT_BASE_URL=https://bugdrop-widget-test-git-preview-jermwatts-projects.vercel.app npx playwright test e2e/widget.cross-browser-live.spec.ts --project=webkit-cross-browser-live --workers=1
```
--------------------------------
### Dev Server Command
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/plans/2026-04-06-custom-area-screenshot.md
Command to start the local development server for manual testing.
```bash
npx wrangler dev
```
--------------------------------
### Complete Bugdrop Widget Configuration Example
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/website/configuration.mdx
A comprehensive example demonstrating multiple configuration options for the Bugdrop widget, including theme, position, color, user input fields, and button dismissibility.
```html
```
--------------------------------
### Basic BugDrop Configuration
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/website/configuration.mdx
This example shows a basic configuration with a repository, dark theme, bottom-left position, and a custom welcome message.
```html
```
--------------------------------
### Run Cross-Browser Live Test Helper
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/plans/2026-05-15-merge-queue-cross-browser-preview.md
Example command to execute the cross-browser live test helper for the Chromium browser in a preview environment.
```bash
LIVE_TARGET=preview PLAYWRIGHT_BASE_URL=https://bugdrop-widget-test-git-preview-jermwatts-projects.vercel.app make test-live-cross-browser BROWSER=chromium
```
--------------------------------
### Run BugDrop Board Guided Demo Polish Goal
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/goals/bugdrop-board-guided-demo-polish/goal.md
This command initiates the BugDrop Board Guided Demo Polish goal, following the instructions defined in the specified markdown file.
```text
/goal Follow docs/goals/bugdrop-board-guided-demo-polish/goal.md.
```
--------------------------------
### Install Semantic Release Packages
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/plans/2026-02-23-ci-improvements-plan.md
Installs the necessary semantic-release packages for automated versioning and changelog generation.
```bash
cd /tmp/bugdrop && npm install --save-dev semantic-release @semantic-release/changelog @semantic-release/git
```
--------------------------------
### Enumerate GitHub App Installations
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/specs/2026-04-04-org-transfer-and-marketplace-design.md
Use this command to generate a JWT and list all installations of a GitHub App. This is crucial for understanding the current deployment before migrating.
```bash
# Generate JWT from old app's private key, then:
curl -H "Authorization: Bearer $JWT" \
https://api.github.com/app/installations
```
--------------------------------
### Clone, Install, and Configure BugDrop
Source: https://github.com/mean-weasel/bugdrop/blob/main/SELF_HOSTING.md
Clone the BugDrop repository, install dependencies, and set up environment variables for local development. This includes copying example configuration files and editing them with your GitHub App credentials.
```bash
git clone https://github.com/YOUR_USERNAME/bugdrop
cd bugdrop
make install
# Configure environment
cp .dev.vars.example .dev.vars
```
```bash
GITHUB_APP_ID=123456
GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
...your key content...
-----END RSA PRIVATE KEY-----"
```
```bash
GITHUB_APP_NAME=your-app-name
```
```bash
cp public/test/local-config.example.js public/test/local-config.js
```
```js
window.BugDropTestConfig = {
...(window.BugDropTestConfig || {}),
repo: 'your-org/your-repo',
};
```
--------------------------------
### Build and Run E2E Tests
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/plans/2026-02-23-ci-improvements-plan.md
Builds the widget, installs Playwright, and runs end-to-end tests.
```bash
cd /tmp/bugdrop && make build-widget && make install-playwright && make test-e2e
```
--------------------------------
### Install Playwright and Browsers
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/website/ci-testing.mdx
Install Playwright and its required browsers using npm and npx. This is a prerequisite for running the tests.
```bash
npm install --save-dev @playwright/test
npx playwright install
```
--------------------------------
### Basic BugDrop Installation
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/website/getting-started.mdx
This is the simplest way to install BugDrop. Add this script tag to your HTML to enable the bug reporting widget on your site.
```html
```
--------------------------------
### Run Screenshot Benchmark
Source: https://github.com/mean-weasel/bugdrop/blob/main/benchmarks/README.md
Execute the screenshot threshold benchmark. This command starts the necessary development server and runs multiple test cases sequentially in a headless browser.
```bash
npm run benchmark:screenshot
```
--------------------------------
### Basic Usage Example
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/website/javascript-api.mdx
Demonstrates the fundamental usage of BugDrop's JavaScript API methods and properties.
```javascript
window.BugDrop.open();
window.BugDrop.close();
window.BugDrop.hide();
window.BugDrop.show();
if (window.BugDrop.isOpen) {
console.log('Form is currently open');
}
if (window.BugDrop.isButtonVisible) {
console.log('Button is visible');
}
```
--------------------------------
### Run BugDrop Locally
Source: https://github.com/mean-weasel/bugdrop/blob/main/SELF_HOSTING.md
Start the local development server for BugDrop. The application will be accessible at http://localhost:8787.
```bash
make dev
# Opens http://localhost:8787
```
--------------------------------
### Update createModal calls to show version on install prompt
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/plans/2026-04-06-remove-version-from-screens.md
In `src/widget/index.ts`, update the `showInstallPrompt` function to pass `true` as the fourth argument to `createModal`, ensuring the version badge is displayed.
```typescript
createModal(root, title, installContent, true);
```
--------------------------------
### localStorage Key for Welcome Persistence
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/specs/2026-04-03-welcome-screen-controls-design.md
Defines the format for the localStorage key used to track whether the welcome screen has been shown to a user for a specific repository. Example: `bugdrop_welcomed_neonwatty/bugdrop`.
```plaintext
bugdrop_welcomed_{repo}
```
--------------------------------
### HTML Script Tag with data-welcome Attribute
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/specs/2026-04-03-welcome-screen-controls-design.md
Example of how to use the `data-welcome` attribute on the script tag to configure or disable the welcome screen. Setting it to 'false' is an alias for 'never'.
```html
```
--------------------------------
### Attach system theme listener in exposeBugDropAPI
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/plans/2026-04-15-runtime-theme-api.md
Install a `matchMedia` listener within `exposeBugDropAPI` to enable the widget to automatically follow OS theme changes when the theme is set to 'auto'. This listener is persistent and only active when `_currentMode` is 'auto'.
```typescript
// Fix for data-theme="auto" not following OS changes after init.
// One persistent listener gated by _currentMode === 'auto'.
_detachSystemListener = attachSystemThemeListener((resolved) => {
if (_currentMode !== 'auto') return;
applyThemeClass(root, resolved);
applyCustomStyles(root, config, resolved);
});
```
--------------------------------
### Screenshot Benchmark JSON Output
Source: https://github.com/mean-weasel/bugdrop/blob/main/benchmarks/README.md
Example JSON file output from the benchmark, containing machine specifications and detailed results for each test case, including node count, actual nodes, duration, and outcome.
```json
{
"timestamp": "2026-04-09T13:30:15.960Z",
"machine": {
"os": "darwin 25.3.0 (arm64)",
"cpu": "Apple M2 Pro",
"cores": 12,
"ramGb": 32
},
"results": [
{ "nodes": 1000, "actualNodes": 1107, "durationMs": 1541, "outcome": "success" },
{ "nodes": 10000, "actualNodes": 11007, "durationMs": 8031, "outcome": "success" },
{ "nodes": 15000, "actualNodes": 16507, "durationMs": 60000, "outcome": "timeout" }
]
}
```
--------------------------------
### Protecting Sensitive Data in Installation Docs
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/plans/2026-05-10-screenshot-privacy-masking.md
This example shows how to integrate the screenshot masking documentation into the installation guide. It demonstrates marking a customer row with `data-bugdrop-mask` and mentions automatic masking for passwords and credit card fields.
```mdx
## Protecting sensitive data
If your page renders customer data, billing details, or any other content you do not
want to appear in submitted screenshots, mark those elements with `data-bugdrop-mask`:
```html
Jane Doe — jane@acme.com
```
BugDrop covers each marked element with an opaque rectangle on the captured screenshot.
Password inputs and credit-card autocomplete fields are masked automatically. See
[Screenshot masking](/security#screenshot-masking) on the Security page for details.
```
--------------------------------
### Build all project components
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/plans/2026-04-03-welcome-screen-controls.md
Initiate a comprehensive build process for all project components using the `make build-all` command. Expected outcome is a successful build.
```bash
make build-all
```
--------------------------------
### Playwright Test Example
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/plans/2026-05-15-merge-queue-cross-browser-preview.md
An example Playwright test assertion for checking element visibility.
```typescript
await expect(host.locator('css=p >> text=too complex')).toBeVisible();
return;
}
await expect(host.locator('css=[data-action="capture"]')).toBeVisible();
await expect(host.locator('css=[data-action="area"]')).toBeVisible();
});
});
```
--------------------------------
### Install Playwright in CI
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/website/ci-testing.mdx
Install Playwright and its dependencies within your CI environment, specifically for the Chromium browser.
```yaml
- name: Install Playwright
run: npx playwright install --with-deps chromium
```
--------------------------------
### Create Benchmark Directories
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/plans/2026-04-09-screenshot-threshold-benchmark.md
Creates the necessary directory for benchmark results and a placeholder file.
```bash
mkdir -p benchmarks/results
touch benchmarks/results/.gitkeep
```
--------------------------------
### Run Goal Command
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/goals/bugdrop-board-demo-ux-polish/goal.md
This command initiates the goal process as defined in the documentation.
```text
/goal Follow docs/goals/bugdrop-board-demo-ux-polish/goal.md.
```
--------------------------------
### Build Widget
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/plans/2026-04-06-custom-area-screenshot.md
Execute the build command for the widget to incorporate the new screenshot functionality.
```bash
npm run build:widget
```
--------------------------------
### Run Full Test Suite
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/plans/2026-05-10-screenshot-privacy-masking.md
This command executes all tests, including unit, integration, E2E, and linting, to ensure the project's stability and correctness after implementing new features or documentation. It's the final verification step before pushing changes.
```bash
npm test # Unit + integration: ~141 tests (was 116)
npm run build:widget
npm run test:e2e # E2E: existing tests + 11 new Screenshot Masking tests
npm run lint # ESLint
```
--------------------------------
### Widget Configuration for Welcome Screen
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/specs/2026-04-03-welcome-screen-controls-design.md
Defines the possible values for the `welcome` configuration option, which controls the display frequency of the welcome screen. The default is 'once'.
```typescript
welcome: 'once' | 'always' | 'never'; // default: 'once'
```
--------------------------------
### Commit Changes for Welcome State
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/plans/2026-04-03-welcome-screen-controls.md
This bash command demonstrates how to stage and commit the new localStorage helpers and tests for the welcome-seen state.
```bash
git add src/widget/index.ts test/welcomeState.test.ts
git commit -m "feat: add localStorage helpers for welcome-seen state"
```
--------------------------------
### Add Cross-Browser Live Preview Job to CI Workflow
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/plans/2026-05-15-merge-queue-cross-browser-preview.md
This YAML configuration defines a new job in the GitHub Actions workflow to run live preview tests across multiple browsers (Chromium, Firefox, WebKit) for merge group events. It handles dependency installation, Playwright browser caching and installation, environment verification, and test execution.
```yaml
live-preview-cross-browser-tests:
name: Live Preview Cross-Browser (${{ matrix.browser }})
runs-on: ubuntu-latest
needs: [deploy-preview]
if: github.event_name == 'merge_group'
strategy:
fail-fast: false
matrix:
browser: [chromium, firefox, webkit]
env:
LIVE_TARGET: preview
PLAYWRIGHT_BASE_URL: https://bugdrop-widget-test-git-preview-jermwatts-projects.vercel.app
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: '22'
cache: 'npm'
- name: Install dependencies
run: make install
- name: Get Playwright version
id: pw-version
run: echo "version=$(npx playwright --version | awk '{print $2}')" >> "$GITHUB_OUTPUT"
- name: Cache Playwright browsers
id: pw-cache
uses: actions/cache@v4
with:
path: ~/.cache/ms-playwright
key: pw-${{ runner.os }}-${{ matrix.browser }}-${{ steps.pw-version.outputs.version }}
- name: Install Playwright browser
if: steps.pw-cache.outputs.cache-hit != 'true'
run: npx playwright install --with-deps ${{ matrix.browser }}
- name: Install Playwright system deps
if: steps.pw-cache.outputs.cache-hit == 'true'
run: npx playwright install-deps ${{ matrix.browser }}
- name: Verify test venue is reachable
run: |
VENUE_URL="${PLAYWRIGHT_BASE_URL}"
echo "Checking test venue at $VENUE_URL..."
BYPASS_ARGS=""
if [ -n "$VERCEL_AUTOMATION_BYPASS_SECRET" ]; then
BYPASS_ARGS="-H x-vercel-protection-bypass:${VERCEL_AUTOMATION_BYPASS_SECRET}"
fi
curl -sfo /dev/null $BYPASS_ARGS "$VENUE_URL" || (echo "Test venue unreachable at $VENUE_URL" && exit 1)
echo "Test venue reachable"
env:
VERCEL_AUTOMATION_BYPASS_SECRET: ${{ secrets.VERCEL_AUTOMATION_BYPASS_SECRET }}
- name: Record expected preview widget asset
run: |
VERSION=$(git describe --tags --abbrev=0) npm run build:widget
echo "EXPECTED_WIDGET_ORIGIN=https://bugdrop-preview.neonwatty.workers.dev" >> "$GITHUB_ENV"
echo "EXPECTED_WIDGET_SHA256=$(shasum -a 256 public/widget.js | awk '{print $1}')" >> "$GITHUB_ENV"
- name: Wait for expected preview widget asset
run: |
WIDGET_URL="https://bugdrop-preview.neonwatty.workers.dev/widget.js"
echo "Waiting for $WIDGET_URL to serve $EXPECTED_WIDGET_SHA256..."
for i in $(seq 1 30); do
ACTUAL_SHA="$(curl -sSf "$WIDGET_URL" | shasum -a 256 | awk '{print $1}')"
if [ "$ACTUAL_SHA" = "$EXPECTED_WIDGET_SHA256" ]; then
echo "Preview widget asset matched after $((i * 5))s"
exit 0
fi
echo "Attempt $i/30 served $ACTUAL_SHA; waiting 5s..."
sleep 5
done
echo "Preview widget did not serve expected asset $EXPECTED_WIDGET_SHA256"
exit 1
- name: Run cross-browser live E2E tests
run: npx playwright test e2e/widget.cross-browser-live.spec.ts --project=${{ matrix.browser }}-cross-browser-live --workers=1
env:
VERCEL_AUTOMATION_BYPASS_SECRET: ${{ secrets.VERCEL_AUTOMATION_BYPASS_SECRET }}
- name: Upload cross-browser report
uses: actions/upload-artifact@v4
if: failure()
with:
name: playwright-cross-browser-report-${{ matrix.browser }}
path: playwright-report/
retention-days: 7
```
--------------------------------
### Commit benchmark README
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/plans/2026-04-09-screenshot-threshold-benchmark.md
Stage and commit the newly created benchmarks/README.md file.
```bash
git add benchmarks/README.md
git commit -m "docs: add benchmark README with contributor instructions"
```
--------------------------------
### Import Vitest Matchers
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/plans/2026-05-10-screenshot-privacy-masking.md
Imports necessary functions from Vitest for testing. Ensure Vitest is installed and configured.
```typescript
import { describe, it, expect, beforeEach } from 'vitest';
```
--------------------------------
### Run Linting
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/plans/2026-04-06-remove-version-from-screens.md
Command to execute the linting process for the project.
```bash
npm run lint
```
--------------------------------
### BugDrop Submitter Information Collection
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/website/configuration.mdx
Example of configuring the BugDrop form to show and require both name and email fields.
```html
```
--------------------------------
### Build and Test Widget
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/plans/2026-04-06-remove-version-from-screens.md
Commands to build the widget and run the updated E2E test specifically for the version badge.
```bash
npm run build:widget && npx playwright test e2e/widget.spec.ts --grep "version number"
```
--------------------------------
### Keyboard Shortcut Example
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/website/javascript-api.mdx
Implements a keyboard shortcut (Ctrl+Shift+B or Cmd+Shift+B) to toggle the BugDrop feedback form for power users.
```javascript
document.addEventListener('keydown', function (e) {
if ((e.ctrlKey || e.metaKey) && e.shiftKey && e.key === 'B') {
e.preventDefault();
if (window.BugDrop && window.BugDrop.isOpen) {
window.BugDrop.close();
} else if (window.BugDrop) {
window.BugDrop.open();
}
}
});
```
--------------------------------
### Implementation of getSystemTheme
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/plans/2026-04-15-runtime-theme-api.md
This function detects the user's system theme preference by checking `window.matchMedia`. It defaults to 'light' if the API is unavailable.
```typescript
export function getSystemTheme(): ResolvedTheme {
if (typeof window !== 'undefined' && window.matchMedia) {
return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
}
return 'light';
}
```
--------------------------------
### Run Tests Command
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/plans/2026-05-10-screenshot-privacy-masking.md
Command to execute the mask tests using npm and Vitest. This is used to verify test setup and implementation.
```bash
npm test -- test/mask.test.ts
```
--------------------------------
### Run Unit Tests
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/plans/2026-04-06-remove-version-from-screens.md
Command to execute the unit test suite for the project.
```bash
npm test
```
--------------------------------
### Unit Tests for Welcome Configuration Parsing
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/plans/2026-04-03-welcome-screen-controls.md
These unit tests verify the logic for parsing the 'data-welcome' attribute to determine the welcome screen behavior. They cover default, explicit 'never', 'always', and unrecognized values.
```typescript
import { describe, it, expect } from 'vitest';
type WelcomeMode = 'once' | 'always' | 'never';
function parseWelcome(value: string | undefined): WelcomeMode {
if (value === 'false' || value === 'never') return 'never';
if (value === 'always') return 'always';
return 'once';
}
describe('Welcome config parsing', () => {
it('defaults to "once" when omitted', () => {
expect(parseWelcome(undefined)).toBe('once');
});
it('returns "never" for "false"', () => {
expect(parseWelcome('false')).toBe('never');
});
it('returns "never" for "never"', () => {
expect(parseWelcome('never')).toBe('never');
});
it('returns "always" for "always"', () => {
expect(parseWelcome('always')).toBe('always');
});
it('defaults to "once" for unrecognized values', () => {
expect(parseWelcome('banana')).toBe('once');
expect(parseWelcome('')).toBe('once');
});
});
```
--------------------------------
### Get System Theme Function Signature
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/specs/2026-04-15-runtime-theme-api-design.md
Signature for a function that reads the system's preferred color scheme once. It falls back to 'light' in non-browser environments.
```typescript
// Reads window.matchMedia once. Falls back to 'light' in non-browser environments.
export function getSystemTheme(): ResolvedTheme;
```
--------------------------------
### Self-Hosted BugDrop Script Tag Example
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/website/self-hosting.mdx
Update your website's script tag to point to your self-hosted BugDrop Worker URL. This ensures feedback is sent to your own instance.
```html
```
```html
```
--------------------------------
### Run Full E2E Test Suite
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/plans/2026-04-06-remove-version-from-screens.md
Command to execute the entire End-to-End test suite.
```bash
npx playwright test
```
--------------------------------
### Run Linting
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/plans/2026-02-23-ci-improvements-plan.md
Executes the linting process for the project.
```bash
cd /tmp/bugdrop && make lint
```
--------------------------------
### Screenshot Benchmark Terminal Output
Source: https://github.com/mean-weasel/bugdrop/blob/main/benchmarks/README.md
Example of the markdown table output from the screenshot benchmark, showing machine information and performance results for different DOM node counts.
```markdown
## Screenshot Threshold Benchmark Results
**Machine:** Apple M2 Pro | 12 cores | 32 GB RAM | darwin 25.3.0 (arm64)
| Nodes (target) | Nodes (actual) | Duration (ms) | Outcome |
|---------------:|---------------:|--------------:|---------|
*Nodes (target) = requested via ?nodes=N; Nodes (actual) = total DOM nodes counted after generation*
| 1000 | 1107 | 1541 | success |
| 3000 | 3307 | 3328 | success |
| 7000 | 7707 | 5793 | success |
| 10000 | 11007 | 8031 | success |
| 15000 | 16507 | 11693 | success |
```
--------------------------------
### Build and Test Widget Command
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/plans/2026-04-06-custom-area-screenshot.md
Commands to build the widget and run the specific E2E test for the area picker functionality.
```bash
npm run build:widget && npx playwright test e2e/widget.spec.ts --grep "select area button"
```
--------------------------------
### JavaScript Function to Get BugDrop Token
Source: https://github.com/mean-weasel/bugdrop/blob/main/SELF_HOSTING.md
An asynchronous JavaScript function that fetches a BugDrop token from a specified API endpoint. It includes error handling for the fetch request.
```javascript
window.getBugDropToken = async function getBugDropToken() {
const response = await fetch('/api/bugdrop-token', { credentials: 'include' });
if (!response.ok) throw new Error('Unable to create BugDrop token');
const { token } = await response.json();
return token;
};
```
--------------------------------
### Define Auth Token Provider Function
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/website/configuration.mdx
Define a global JavaScript function to fetch authentication tokens from your backend. This function is called by BugDrop before installation checks and feedback submissions.
```html
```
--------------------------------
### Test cases for getSystemTheme
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/plans/2026-04-15-runtime-theme-api.md
These tests mock `window.matchMedia` to verify that `getSystemTheme` correctly returns 'dark' or 'light' based on system preferences. It also tests the fallback behavior when `matchMedia` is unavailable.
```typescript
describe('getSystemTheme', () => {
const originalMatchMedia = window.matchMedia;
afterEach(() => {
window.matchMedia = originalMatchMedia;
});
function mockMatchMedia(matches: boolean) {
window.matchMedia = vi.fn().mockImplementation(() => ({
matches,
media: '(prefers-color-scheme: dark)',
addEventListener: vi.fn(),
removeEventListener: vi.fn(),
addListener: vi.fn(),
removeListener: vi.fn(),
dispatchEvent: vi.fn(),
onchange: null,
})) as unknown as typeof window.matchMedia;
}
it('returns "dark" when prefers-color-scheme matches', () => {
mockMatchMedia(true);
expect(getSystemTheme()).toBe('dark');
});
it('returns "light" when prefers-color-scheme does not match', () => {
mockMatchMedia(false);
expect(getSystemTheme()).toBe('light');
});
it('returns "light" when matchMedia is unavailable', () => {
// @ts-expect-error - deliberately removing
delete window.matchMedia;
expect(getSystemTheme()).toBe('light');
});
});
```
--------------------------------
### Build the Widget
Source: https://github.com/mean-weasel/bugdrop/blob/main/SELF_HOSTING.md
Compile the widget source code before the development server can serve it. The built files are not committed to git.
```bash
make build-widget
```
--------------------------------
### Configure Preview Environment in wrangler.toml
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/plans/2026-04-04-preview-deployment-tests.md
Add a new `[env.preview]` section to your `wrangler.toml` file to define settings for the preview deployment environment. This includes environment variables and KV namespace bindings.
```toml
# Preview environment for live E2E tests (deployed in merge queue)
[env.preview]
name = "bugdrop-preview"
[env.preview.vars]
ENVIRONMENT = "preview"
ALLOWED_ORIGINS = "*"
GITHUB_APP_NAME = "neonwatty-bugdrop"
MAX_SCREENSHOT_SIZE_MB = "5"
[[env.preview.kv_namespaces]]
binding = "RATE_LIMIT"
id = ""
```
--------------------------------
### Test Suite for Explicit Mask Attribute
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/plans/2026-05-10-screenshot-privacy-masking.md
Tests the functionality of collecting mask rectangles when elements have the `data-bugdrop-mask` attribute. Includes setup for resetting the DOM and scroll position before each test.
```typescript
describe('collectMaskRects — explicit attribute', () => {
beforeEach(() => {
document.body.replaceChildren();
Object.defineProperty(window, 'scrollX', { value: 0, configurable: true });
Object.defineProperty(window, 'scrollY', { value: 0, configurable: true });
});
it('returns empty array for clean DOM', () => {
expect(collectMaskRects(document.body)).toEqual([]);
});
it('returns rect for a single masked div', () => {
const div = withRect(document.createElement('div'), 10, 20, 100, 50);
div.setAttribute('data-bugdrop-mask', '');
document.body.appendChild(div);
expect(collectMaskRects(document.body)).toEqual([{ x: 10, y: 20, w: 100, h: 50 }]);
});
it('returns rects for multiple sibling masked elements', () => {
const a = withRect(document.createElement('div'), 0, 0, 50, 50);
a.setAttribute('data-bugdrop-mask', '');
const b = withRect(document.createElement('div'), 100, 0, 50, 50);
b.setAttribute('data-bugdrop-mask', '');
document.body.append(a, b);
expect(collectMaskRects(document.body)).toEqual([
{ x: 0, y: 0, w: 50, h: 50 },
{ x: 100, y: 0, w: 50, h: 50 },
]);
});
});
```
--------------------------------
### Example 429 Rate Limit Exceeded Response
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/website/security.mdx
This JSON object illustrates the structure of a 429 Too Many Requests response from the BugDrop API, including an error message and the recommended retry delay.
```json
{
"error": "Rate limit exceeded. Please try again later.",
"retryAfter": 420
}
```
--------------------------------
### Inspect Test Page Conventions
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/plans/2026-05-10-screenshot-privacy-masking.md
Lists files in the public/test directory and displays the first 40 lines of public/test/index.html to understand existing test page conventions, particularly script loading.
```bash
ls public/test/
head -40 public/test/index.html
```
--------------------------------
### Programmatically Show/Hide BugDrop Widget
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/website/javascript-api.mdx
Control the visibility of the floating BugDrop button using `window.BugDrop.show()` and `window.BugDrop.hide()`. This example demonstrates hiding the button on a checkout page and showing it when a help section is opened.
```javascript
```
--------------------------------
### Run Project Tests and Checks
Source: https://github.com/mean-weasel/bugdrop/blob/main/CONTRIBUTING.md
Execute unit tests, end-to-end tests, linting, type checking, and the full CI pipeline.
```bash
make test # Unit tests
make test-e2e # E2E tests (requires Playwright)
make check # Lint + typecheck + knip
make ci # Full CI pipeline
```
--------------------------------
### Add Explicit Assets Configuration (if needed)
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/plans/2026-04-04-preview-deployment-tests.md
If the `[assets]` configuration is not inherited by the preview environment, add it explicitly within the `[env.preview.assets]` section of `wrangler.toml`.
```toml
[env.preview.assets]
directory = "public"
binding = "ASSETS"
```
--------------------------------
### Area Picker Module Implementation
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/plans/2026-04-06-custom-area-screenshot.md
This TypeScript code defines the core logic for an area picker, handling mouse and keyboard events for selecting a region. It includes setup for event listeners and cleanup functions.
```typescript
function onKeyDown(e: KeyboardEvent) {
if (e.key === 'Escape') {
cleanup();
resolve(null);
}
}
function cleanup() {
overlay.removeEventListener('mousedown', onMouseDown);
document.removeEventListener('mousemove', onMouseMove);
document.removeEventListener('mouseup', onMouseUp);
document.removeEventListener('keydown', onKeyDown);
overlay.remove();
selectionBorder.remove();
tooltip.remove();
}
overlay.addEventListener('mousedown', onMouseDown);
document.addEventListener('mousemove', onMouseMove);
document.addEventListener('mouseup', onMouseUp);
document.addEventListener('keydown', onKeyDown);
```
--------------------------------
### Test Auto Mode Theme Switching via page.emulateMedia
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/plans/2026-04-15-runtime-theme-api.md
Verifies that the 'auto' theme mode correctly follows OS theme changes emulated using `page.emulateMedia`. Ensure the `colorScheme` is set before testing.
```typescript
test('auto mode follows OS theme changes via page.emulateMedia', async ({ page }) => {
await page.emulateMedia({ colorScheme: 'light' });
await gotoWidget(page, { theme: 'auto' });
expect(await rootClassList(page)).not.toContain('bd-dark');
await page.emulateMedia({ colorScheme: 'dark' });
// Give the matchMedia change event a tick to propagate
await page.waitForFunction(() => {
const host = document.querySelector('[data-bugdrop-host]') as HTMLElement | null;
const root = host?.shadowRoot?.querySelector('.bd-root') as HTMLElement | null;
return root?.classList.contains('bd-dark') === true;
});
expect(await rootClassList(page)).toContain('bd-dark');
});
```
--------------------------------
### Bold Brutalist Design Styling
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/website/styling.mdx
Achieve a bold, high-contrast brutalist aesthetic with monospace fonts, sharp corners, and hard shadows. This example uses data attributes for a raw, technical feel with black and white contrast and a red accent.
```html
```
--------------------------------
### Elegant Serif Site Styling
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/website/styling.mdx
Apply classic serif fonts, minimal border radius, and warm accents for a sophisticated editorial style. This example uses specific data attributes for font, radius, background, text color, border, shadow, and accent color.
```html
```
--------------------------------
### Push Preview Branch to Origin
Source: https://github.com/mean-weasel/bugdrop/blob/main/docs/superpowers/specs/2026-04-04-org-transfer-and-marketplace-design.md
Create and push a new 'preview' branch to your Git repository to initiate a Vercel preview deployment.
```bash
git checkout -b preview
git push -u origin preview
```