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. Drop it into any BrowserSync project and forget it's there — it only activates 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 development server (any project using browser-sync)
• 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 to show or hide the panel.

Adding comps

• Click Import to load all images from a local references/ folder. In supported browsers, choose the repo's references folder and Bullseye imports its images recursively
• If directory import is not supported, Import falls back to served references/ discovery when the dev server exposes directory links for references/, or when references/manifest.json, references/references.json, or references/images.json lists image paths
• 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

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, in 0.5 steps)

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
• Click Log to view the changelog inside the panel

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

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 auth token is saved in ~/.npmrc — no login needed.

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