Bullseye

A localhost-only dev tool for pixel-checking PNG design comps against a live page, plus a viewport badge that shows current breakpoint and dimensions.

Bundled as a single minified file (dist/development-tools.js) that includes both tools. Supports BrowserSync and Vite (including Astro) on localhost.

What's included

Viewport badge

A small fixed badge in the top-left corner of the browser that shows the current viewport dimensions (1440 x 900). If the page uses a --kindling-breakpoint CSS variable, the badge also shows the active breakpoint (bp: lg | 1440 x 900). Click the badge to dismiss it.

The viewport badge is suppressed on detected banner pages so banner previews only show Bullseye.

Bullseye overlay

A draggable panel for loading PNG comp images and overlaying them on the page at adjustable opacity. Useful for checking spacing, alignment, and proportions against a live build.

Requirements

• A local BrowserSync or Vite development server (including Astro)
• The tool only initializes on localhost, 127.0.0.1, 0.0.0.0, or ::1

Setup

Add the script to your project's dev HTML, after BrowserSync's own injected script:

<script src="node_modules/@archerinteractive/bullseye/dist/development-tools.js"></script>

Or reference it from your build pipeline however you handle dev-only scripts.

Using Bullseye

Press B on any page running through BrowserSync or Vite to show or hide the panel. Vite is detected through its injected /@vite/client script, including base-prefixed URLs; no BrowserSync marker is needed.

Adding comps

• Click IMPORT ALL to load PNGs directly inside repo/references/ at 0.5 scale. The folder is scanned only when clicked, never automatically on page load. Click again after adding PNGs to the folder; existing reference URLs are not duplicated, and saved layers keep their positions and scale.
• IMPORT ALL reads the origin-root /references/ folder without opening a folder picker. It uses directory links or manifest.json, references.json, or images.json exposed by your development server. See the setup below if your server does not list directories or serves from dist/.
• Click Add new in the panel to open a file picker
• In browsers that support the enhanced file picker, selecting from a repo's references folder once lets Bullseye reopen that folder on future adds when the browser allows it
• Drag one or more PNG files directly onto the page while the panel is open

Serving the repo's references folder

For Vite or Astro, register the included Vite plugin:

import bullseyeReferences from '@archerinteractive/bullseye/vite.js';

// vite.config.js
export default { plugins: [bullseyeReferences()] };

// Astro: add vite: { plugins: [bullseyeReferences()] } to defineConfig().

It serves the Vite root's references/ folder only during development. If the repo root differs from Vite's root, pass bullseyeReferences({ root: '/absolute/path/to/repo' }). Reference files are not copied into production builds or served by the production preview server. Registration uses Vite's development server hook.

Import the browser overlay from your development entry (or an Astro component's <script>):

if (import.meta.env.DEV) {
  import('@archerinteractive/bullseye');
}

Keep the development guard so the overlay is excluded from production builds. In Kindling's visual-check integration, keep the existing __visual_check exclusion as well.

For BrowserSync projects without a directory listing, add the included middleware to the existing BrowserSync configuration. Pass the repo root if your config runs from another directory:

const references = require('@archerinteractive/bullseye/references-middleware');

browserSync.init({
  server: { baseDir: 'dist' },
  middleware: [references(process.cwd())]
});

Keep any existing middleware in that array. This serves /references/manifest.json and the PNG files directly from repo/references/, with no copying or manual manifest updates. The helper accepts localhost connections only and does not serve other file types or nested folders.

Alternatively, expose the folder with directory listings, or provide references/manifest.json containing filenames such as ["desktop.png", "mobile.png"] and serve those images at /references/. A browser script cannot list arbitrary files on disk without the dev server exposing them.

Working with layers

Each loaded comp is a layer. Only one layer is active (visible) at a time — selecting a thumbnail activates that layer and deactivates the rest.

| Control | What it does | |---|---| | Show | Toggles the active layer on or off | | Lock | Prevents the layer from being dragged | | Reset | Restores position to X: 0, Y: 0, scale: 1, opacity: 50% | | Opacity slider | Fades the comp over the page (default 50%) | | ✕ | Removes the layer |

Positioning

• Drag the comp image directly to reposition it
• Use X / Y fields for exact pixel placement
• Use Scale to resize (0 to 4; arrow keys step by 0.25)

Alignment

Snap the active layer using the alignment buttons:

| Button | Behaviour | |---|---| | Top | Snaps layer to Y: 0 | | Left | Snaps layer to X: 0 | | Center | Centers the layer in the viewport and locks it there — the layer stays centered through resizes until you move it or align it left/right | | Right | Snaps layer to the right edge of the viewport |

Panel behaviour

• The panel starts flush to the right edge of the browser
• Drag the panel by its outer frame to reposition it — it snaps to viewport edges when dragged close
• Use the menu button to collapse or expand the panel
• Use the close button or press B to hide it
• If a resize would push a moved panel off-screen, it snaps back to the right edge

Persistence

Layer data (images and positions) is saved to localStorage per page URL, so your layers are restored when you reopen the same page. The panel always starts hidden on load.

GSAP timeline controls

On detected banner pages, Bullseye shows a banner below the comp with playback controls when it finds a usable GSAP timeline:

• Play / Pause toggle
• Scrubber to seek through the timeline
• Timestamp showing the current position in minutes, seconds, and milliseconds (MM:SS.mmm)

Banner detection uses the ad.size meta tag or common fixed ad dimensions. Timeline controls are not shown on non-banner websites just because GSAP is present. On banners, Bullseye checks named timelines exposed on the window object and uses a non-empty gsap.globalTimeline as a fallback.

Publishing updates

1. Edit source files in src/
2. Bump the version in package.json and add a changelog entry in src/bullseye.js
3. Run from ~/www/bullseye:

npm run build && npm publish

The project's npm credentials are saved in its ignored .npmrc file.

Version conventions: patch (0.6.x) for fixes and tweaks, minor (0.x.0) for new features, major (x.0.0) for breaking changes.

Project structure

bullseye/
├── src/
│   ├── dev-badge.js      # Viewport badge IIFE
│   └── bullseye.js       # Overlay tool IIFE
├── dist/
│   └── development-tools.js  # Minified build (both tools concatenated)
├── scripts/
│   └── build.js          # Node build script (terser)
├── package.json
├── LICENSE
└── README.md

License

MIT — Copyright © 2026 Archer Interactive