QA Overlay

A visual QA tool for marking issues on web pages during review. Drop pins on any page element, add notes, and export for analysis.

Features

- Drop numbered pins on any page element
- Add optional notes to each pin
- Pins persist across page reloads (localStorage)
- Export all notes as JSON for review
- Works with any website or web app
- Zero dependencies
- Keyboard shortcuts for quick access

Installation

$3

``html




`

$3

`bash
npm install qa-overlay
`

`javascript
// ES Modules
import { QAOverlay } from 'qa-overlay';
import 'qa-overlay/css';

QAOverlay.init();
`

`javascript
// CommonJS
const { QAOverlay } = require('qa-overlay');
// Note: You'll need to import the CSS separately in your build process

QAOverlay.init();
`

$3

Download qa-overlay.js and qa-overlay.css from the dist/ folder and include them in your project.

Usage

$3

| Shortcut | Action |
|----------|--------|
| Ctrl+Shift+Q | Toggle QA mode on/off |
| Ctrl+Shift+E | Export notes to clipboard as JSON |
| Ctrl+Shift+C | Clear all notes |
| Escape | Close modal or deactivate QA mode |

$3

- Click anywhere on the page (when QA mode is on) to drop a pin
- Right-click a pin to delete it
- Hover over a pin to see its note

$3

`javascript
// Initialize the overlay
QAOverlay.init();

// Toggle QA mode programmatically
QAOverlay.toggle();

// Get all notes
const notes = QAOverlay.getNotes();

// Get notes for current page only
const pageNotes = QAOverlay.getPageNotes();

// Export as JSON string
const json = QAOverlay.exportJSON();

// Clear all notes
QAOverlay.clearNotes();

// Check status
QAOverlay.isActive(); // Is QA mode on?
QAOverlay.isInitialized(); // Has init() been called?

// Clean up (remove from DOM)
QAOverlay.destroy();
`

$3

Each note contains:

`typescript
interface QANote {
id: string; // Unique identifier
pageUrl: string; // Full URL
pagePath: string; // Path portion only
x: number; // Page X coordinate
y: number; // Page Y coordinate
scrollY: number; // Scroll position when placed
viewportX: number; // Viewport X coordinate
viewportY: number; // Viewport Y coordinate
viewportWidth: number; // Browser width when placed
viewportHeight: number; // Browser height when placed
note: string; // User's note text
timestamp: string; // ISO timestamp
}
`

Framework Integration

$3

`astro
---
// src/components/QAOverlay.astro
---



`

$3

`jsx
import { useEffect } from 'react';
import { QAOverlay } from 'qa-overlay';
import 'qa-overlay/css';

function App() {
useEffect(() => {
QAOverlay.init();
return () => QAOverlay.destroy();
}, []);

return

;
}
`

$3

`vue

`

$3

`jsx
// app/layout.js or pages/_app.js
'use client';
import { useEffect } from 'react';

export default function Layout({ children }) {
useEffect(() => {
// Dynamic import to avoid SSR issues
import('qa-overlay').then(({ QAOverlay }) => {
import('qa-overlay/css');
QAOverlay.init();
});
}, []);

return <>{children};
}
`

AI-Assisted QA with Claude

QA Overlay works great with Claude Code's browser tools for automated visual QA. Export your pins and Claude can analyze what each pin is pointing at.

$3

1. Enable QA mode (Ctrl+Shift+Q)
2. Click to place pins on issues
3. Export pins (Ctrl+Shift+E)
4. Share the JSON with Claude
5. Claude uses browser tools to identify what each pin points at

$3

For accurate pin analysis, Claude's browser viewport must match the viewport where pins were created. Each pin stores its viewportWidth - Claude will detect mismatches and ask you to resize.

Mobile pins (< 768px viewport) require the browser to be resized to that width, as responsive layouts change element positions.

Development

`bash


Clone the repo

git clone https://github.com/mattmacrocket/qa-overlay.git
cd qa-overlay

Build dist files

npm run build
``

License

MIT