Introducing a new way to review your PRs.

Read the announcement

pbakaus / impeccable

The design vocabulary for your coding agent. Steer with polish and bolder, review with critique and audit, catch AI slop before it ships.

View on GitHub

32 documents · Updated Nov 20, 2026

docs / extension-page-integration

Extension page integration

The Impeccable browser extension connects browser UI surfaces to a detector that runs against the inspected page. Its manifest grants the needed browser access, the Chrome background worker joins the detector with the walk and account flows, and the detector content script bridges extension messages with page-context events.

Extension boundary

Manifest contract

The home/…/manifest.json file defines the extension as a Manifest V3 package. It names the Chrome background entry, the DevTools entry page, the side panel, and the popup action, so the browser can start the right context for each user entry point. The Chrome entry at extension/…/chrome-worker.js loads the detector coordinator and the workers for the other extension flows; the Firefox build uses its own background entry.

The manifest declares static content scripts for the hosted app pages used by walks and account setup. The detector content script is different: the background worker loads it only after the user engages with a scan surface. This keeps page scanning separate from the page scripts that support the extension's own hosted flows. The package is version 1.4.0 and describes its goal as detecting common UI anti-patterns on web pages.

References: extension/manifest.json• L1-40 extension/…/chrome-worker.js• L1-6

Browser access

The extension uses browser permissions to connect its UI surfaces to the current tab, preserve shared settings, host its rule core, and support related account and walk flows. The <all_urls> host rule makes scan access available across web pages rather than only on a fixed site list. The manifest also grants narrower browser capabilities for tab control, DevTools integration, downloads, identity, notifications, and native messaging.

These permissions do not make every browser page scannable. Protected pages such as browser settings and store pages can reject script injection. Local files also require the user to enable the browser's file-URL access for the extension.

AccessRole in the product
activeTab, scripting, <all_urls>Give a user-initiated scan access to the current page and let the worker load the page bridge.
storage, webNavigation, offscreenShare scan settings, track page changes, and host the rule core outside the page.
debugger, tabs, tabGroups, sidePanelConnect DevTools and side-panel surfaces to the right browser tab.
downloads, identity, alarms, notifications, declarativeNetRequestWithHostAccess, nativeMessagingSupport the extension's account, walk, and browser-integration flows.

References: extension/manifest.json• L7-25 extension/…/service-worker.js• L119-172 extension/…/service-worker.js• L174-195 extension/…/service-worker.js• L422-461

Page connection

Context bridge

The detector content script is the boundary between the extension and the inspected page. It receives commands from the service worker through extension messaging, captures a page snapshot, answers requests that need live page data, and draws the returned findings on the page. Separate manifest content scripts serve the extension's hosted walk and account pages rather than the inspected page.

The rule core runs in the extension's offscreen page instead of the page context. The content script sends the snapshot and scan continuations to that page through runtime messages. This keeps page Content-Security-Policy rules from blocking the WebAssembly core while still allowing the core to ask the live page for hit tests and image data.

The bridge keeps one scan session for the page and treats a newer scan as the current generation. It also supports a separate follow-up session for visual candidates that were outside the viewport. When those elements enter view, the bridge waits for the page to paint, captures current page data, and sends the candidate back to the rule core. This lets the detector complete visual checks without delaying the first result for content that the user cannot see.

The Chrome background worker is the browser entry that composes the detector service worker with the workers for walks and account flows. For scanning, it injects the snapshot helper, overlay helper, and detector content script only after the user engages with an extension surface. A per-tab flag makes repeated injection safe. The content script also guards its own setup against duplicate injection, so event listeners and page overlays are not added more than once. The worker clears its flag when navigation or DevTools teardown destroys the page connection. The offscreen rule core is created lazily in Chrome and hosted in a hidden extension iframe on Firefox, so WebAssembly runs under the extension's policy rather than the page's policy.

References: extension/…/chrome-worker.js• L1-6 extension/…/content-script.js• L1-79 extension/…/content-script.js• L126-189 extension/…/content-script.js• L191-261 extension/…/service-worker.js• L78-155 extension/…/service-worker.js• L174-195 extension/…/service-worker.js• L254-269 extension/…/offscreen.html• L1-13 extension/manifest.json• L55-100

Scan lifecycle

Scanning starts only after an extension surface asks for it. The service worker first ensures that the page-side scripts and offscreen rule core exist, builds a scan configuration from shared settings, and sends the scan command to the tab.

The scan then moves between the page snapshot and the rule core. The content script supplies live answers when the core needs data that a snapshot cannot hold. It draws findings in stages, reports scan measurements with the findings, and schedules visual follow-up work for unresolved content. The service worker forwards the findings to the extension surfaces.

The following flow shows how a user request becomes page findings and then reaches the extension surfaces.

flowchart LR
    U[Popup or DevTools surface] -->|scan request| W[Background service worker]
    W -->|inject if needed| C[Content script and page helpers]
    C -->|snapshot and live-page answers| O[Offscreen rule core]
    O -->|findings and follow-up work| C
    C -->|findings and overlay state| W
    W -->|state and updates| U

The popup starts a scan for the active tab. Opening the DevTools panel or sidebar can also start one, and a user setting can opt into scanning when DevTools opens. The service worker keeps these entry points on the same per-tab state instead of running separate scans for each surface.

The content script can rescan after single-page navigation signals. For visual checks that need an in-view element, it schedules follow-up work when that element enters the viewport and publishes any new finding without replacing the page connection.

References: extension/…/service-worker.js• L162-184 extension/…/service-worker.js• L290-339 extension/…/devtools.js• L21-45 extension/…/panel.js• L188-203 extension/…/popup.js• L66-74 extension/…/content-script.js• L191-227 extension/…/content-script.js• L230-261 extension/…/content-script.js• L306-319

Message-driven coordination

Message routes

Extension messages carry commands and results between the popup, DevTools pages, service worker, content script, and offscreen rule core. Long-lived ports serve DevTools panel, sidebar, and lifecycle connections. Runtime messages carry scans, staged rule work, findings, overlay changes, and page activity.

RoutePurpose
Popup → service workerRequest a scan, toggle overlays, or read the active tab's state.
DevTools surface → service workerRequest scans and overlay actions through a tab-specific port.
Service worker → content scriptStart a scan, change overlays, highlight an element, or remove page state.
Content script ↔ offscreen rule coreStart rule work, continue staged scans, answer page-data requests, and run deferred visual checks.
Content script → service workerReturn findings, scan measurements, overlay state, errors, and page-pointer activity.
Service worker → DevTools surfacesForward findings and state to all connected surfaces for the tab.
Service worker → popupBroadcast findings, overlay state, or a scan failure.

Element highlighting follows the same route as scanning. The DevTools panel sends a selector to the service worker, which sends it to the content script and then to the page overlay. Page pointer activity travels in the opposite direction so the panel can clear a hover highlight when the cursor returns to the page.

References: extension/…/service-worker.js• L186-249 extension/…/service-worker.js• L271-339 extension/…/content-script.js• L51-79 extension/…/content-script.js• L108-115 extension/…/content-script.js• L264-304 extension/…/panel.js• L367-389

Tab state lifecycle

The service worker owns one state record per tab. That record holds the current findings, overlay visibility, scan identity, and injection status, which keeps the badge, popup, panel, and sidebar aligned.

Navigation invalidates page-side state because a reload destroys the content script. The service worker clears findings and both injection flags on every tracked navigation, informs connected DevTools surfaces, and rescans after navigation only when DevTools was already active and the tab had been engaged. The content script also watches single-page navigation signals and asks the detector to scan again after the page settles.

When DevTools closes, its lifecycle port disconnects. The service worker asks the content script to remove page state, clears the tab's findings and injection flags, and removes its panel connections and badge state. Closing a tab removes all remaining in-memory state and connections.

References: extension/…/service-worker.js• L12-25 extension/…/service-worker.js• L254-269 extension/…/service-worker.js• L322-349 extension/…/service-worker.js• L422-461 extension/…/content-script.js• L264-293 extension/…/content-script.js• L306-319

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the Chrome manifest background entry, the Chrome worker imports, and the Firefox manifest derivation compatible when changing the background entry or browser permissions.
  • Keep the injected script list and its helper dependencies aligned with the content script. A missing or reordered helper can make scans fail only after injection.
  • Keep message action names, offscreen targets, session IDs, and tab ID handling aligned across the popup, DevTools ports, service worker, content script, and rule core. A one-sided rename can leave a surface waiting forever.
  • Keep scan generations and deferred visual sessions aligned with overlay and finding updates. A late candidate result must not replace a newer scan.
  • Keep navigation and DevTools teardown reset rules aligned with both injection flags and page-side observers. A stale flag or observer can affect the next page.
  • Keep scan-setting and scan-stat changes flowing through the service worker so active tabs and extension surfaces receive the same view of a run.

Important failure modes

TriggerConsequenceGuard
The target is a protected browser page or a local file without file-URL access.Script injection fails and no findings reach the UI.The service worker returns a scan-failed message and gives a local-file access hint.
The offscreen rule core cannot start or does not answer.The page-side integration is present but the scan produces no findings.The service worker waits for a ready response and reports a scan failure if startup times out or errors.
A tab reloads while its old injection flags remain set.A later scan can be treated as a no-op even though the new page has no listener.Navigation clears findings and all injection flags before any rescan.
A scan session is superseded by a newer scan.Late results from the old scan can overwrite current overlays or findings.The content script uses scan generations and session IDs to ignore superseded work.
A deferred visual candidate is resolved after a newer scan starts.A late visual result can attach to stale page elements or findings.The content script checks the scan generation before and after candidate analysis.
The Manifest V3 service worker stops while a DevTools surface remains open.The old port becomes invalid and state updates can stop.DevTools reconnects ports and sends periodic keepalive messages.
A DevTools panel or sidebar connects before findings exist.The surface can show an empty state without a scan.The service worker sends the current state and starts a scan when no findings exist.

Key files

FileWhy to read it
extension/manifest.jsonDefines the browser contexts, permissions, host access, static page scripts, and extension page policy.
extension/…/chrome-worker.jsShows the Chrome background entry that joins the detector, walk, and account workers.
extension/…/service-worker.jsShows the central tab state, dynamic injection, offscreen startup, message routes, and navigation lifecycle.
extension/…/content-script.jsShows the boundary between extension messaging, page data, staged scans, deferred visual work, and offscreen rule-core messaging.
extension/…/offscreen.htmlShows the extension page that hosts the WebAssembly rule core.
extension/…/devtools.jsShows how DevTools lifetime and optional auto-scan connect to the service worker.
extension/…/panel.jsShows how findings and user actions use the tab-specific panel port.
extension/…/popup.jsShows the active-tab entry point and popup state updates.
scripts/build-extension.jsShows how the detector artifact is produced and how the Firefox package derives its background declaration.