The Toolbar Badge

## Why it matters

At a glance, you want to know whether Scalpel is working on this page and how hard. The badge tells you instantly. A number means blocking is active and that's how many requests were stopped. OFF means you've turned blocking off for this page. A quick look at the icon tells you whether the page is getting the full filter or not.

The badge is also honest about its limits. It only counts what Scalpel can see: requests on the page you're looking at, measured at the moment you open the popup. It doesn't watch background tabs or keep a global running total.

## How it works

Every tab gets its own badge. When you load a page, Scalpel opens the popup and calls declarativeNetRequest.getMatchedRules for that active tab. Chrome tells it how many requests were blocked by the static rulesets on this page. Scalpel displays that number on the icon.

The badge reads OFF when either of two things is true:

1. The site is on your allowlist, so blocking is turned off for its domain.
2. Blocking is globally paused, so nothing is being blocked anywhere until you switch it back on.

When you switch tabs, the badge updates to show the blocked count for the new tab, or OFF if that site is allowlisted or blocking is paused. The number is always per-tab, never a total across all tabs.

## What does not matter

The blocked count is not exact across your whole browsing day. Scalpel only counts requests on pages where you open the popup. If you have ten news sites open in background tabs and never click the popup on them, their counts are not tallied into a global total. Honest under-count beats a fabricated number.

The badge doesn't show how many trackers were blocked, only total requests. A page might load five tracker scripts and fifty ad images; the badge shows 55, not broken down by type. Scalpel works at the network level, so it sees "request blocked" but not always what the request was for.

If you switch tabs, the badge updates immediately. On one tab it might show 42, on the next tab it shows OFF. The number is never cumulative across tabs.

## Code example

Here's what happens behind the scenes when you open the popup on a page:

// Ask Chrome how many rules matched on this tab
chrome.declarativeNetRequest.getMatchedRules(
  { tabId: activeTabId },
  (result) => {
    const blockedCount = result.rulesMatchedInfo.length;
    // Set the badge text
    if (allowlist.includes(domain)) {
      chrome.action.setBadgeText({ text: "OFF", tabId: activeTabId });
    } else if (isGloballyPaused) {
      chrome.action.setBadgeText({ text: "OFF", tabId: activeTabId });
    } else {
      chrome.action.setBadgeText({
        text: String(blockedCount),
        tabId: activeTabId
      });
    }
  }
);
Copy

The getMatchedRules call requires a user gesture (you clicking the popup), so Scalpel only counts when you ask to see it. No background counting, no steady logging.

## How Scalpel Ads Blocker shows it

Look at the Scalpel icon in your toolbar. On most pages, you'll see a number. That's the blocked count for the active tab. Click the icon and the popup opens, showing more detail about what's happening.

If the badge shows OFF, the page is either allowlisted or blocking is globally paused. Open the popup to check which. The colour of the badge (usually green when blocking is active, grey when it's off) gives you a quick visual cue.

Click on a different tab in your browser and the badge updates to show that tab's count. The number is specific to the tab you're on right now.