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-devtools-and-popup

Extension DevTools and popup interfaces

The extension gives engineers two ways to review a scanned page: a full Impeccable panel and an element-focused sidebar inside Chrome DevTools, plus a small popup for quick actions. These surfaces share per-tab findings and overlay state through the extension runtime, so a scan or display change in one surface can update the others.

Interface surfaces

The interfaces serve different levels of inspection. The panel gives a page-wide view and controls, the sidebar explains the selected element, and the popup gives fast access without opening DevTools. The browser extension product provides the wider product context, while extension page integration explains the page and runtime boundary.

DevTools panel

The DevTools panel is the main review surface for all findings on the inspected page. It groups findings into AI tells, quality issues, and advisories, then groups each type so an engineer can move from a broad count to a specific selector and detail. Findings for page-level issues and hidden elements remain visible, while only usable element findings support direct inspection.

The panel supports the main review actions:

  • Re-scan the page.
  • Show or hide page overlays.
  • Expand or collapse finding groups.
  • Hover a finding to highlight its matching page element.
  • Click an element finding to scroll to it and select it in DevTools.
  • Copy one finding or the full report for use in an issue or design workflow. The copied text can include the inspected page URL and suggested Impeccable skills for the detected findings.

The panel also exposes preferences that affect later scans and highlights. Engineers can choose when automatic scanning starts, set the line-length threshold, enable or disable highlight blur, and turn individual detector rules on or off. These rules are grouped by the same AI tell, quality, and advisory categories used in the findings view.

The panel follows the active DevTools light or dark theme. It keeps a connection to the extension runtime while open and restores that connection when the runtime service restarts.

References: extension/…/devtools.js• L9-19 extension/…/panel.html• L9-71 extension/…/panel.js• L8-33 extension/…/panel.js• L36-69 extension/…/panel.js• L112-225 extension/…/panel.js• L227-289 extension/…/panel.js• L291-409 extension/…/panel.css• L31-148 extension/…/panel.css• L392-653

Elements sidebar

The Elements sidebar is a focused view of the element selected in Chrome DevTools. It compares the current selection, known as $0 in DevTools, with the selectors in the page findings and shows only the findings that match that element.

The sidebar changes as selection changes. It shows a prompt before results exist, a clean state when the selected element has no findings, or each matching finding with its kind, detail, and description. Page-level findings and hidden elements do not appear because they cannot identify the selected visible element.

References: extension/…/devtools.js• L15-19 extension/…/sidebar.html• L8-12 extension/…/sidebar.js• L11-66 extension/…/sidebar.js• L69-103 extension/…/sidebar.css• L15-94

The popup is a quick control surface for the active tab in the current browser window. It shows the total anti-pattern count and provides actions to copy the full report, scan the page, or change overlay visibility. It does not replace the panel’s detailed review; it gives a short path to act on the current result.

The popup reads the active tab state when it opens and listens for updates while it remains open. It enables copying only for a completed scan that still belongs to the current page. Navigation or a tab change clears the old result, and a failed scan leaves the count and copy action reset while showing an error. Overlay visibility remains available as a tab-level state even when scan findings are no longer valid.

References: extension/manifest.json• L34-38 extension/…/popup.html• L14-38 extension/…/popup.css• L17-79 extension/…/popup.js• L42-75 extension/…/popup.js• L77-120 extension/…/popup.js• L132-169

Options page

The options page is the account and local agent-permission surface for the extension. It reports whether the browser is signed in, offers sign-in or sign-out, and in an unpacked development build allows the account server to be changed.

The page also lists sites that the person has chosen to always allow for their local agent. Removing a site updates browser-local storage, so the agent uses the new allowlist for later site checks. Account words are kept in one shared popup vocabulary so the account view and popup-related surfaces use the same labels.

References: extension/manifest.json• L34-38 extension/…/settings.html• L20-35 extension/…/settings.js• L7-39 extension/…/settings.js• L41-64 extension/…/words.js• L1-15 extension/…/worker.js• L21-31 extension/…/worker.js• L55-72 extension/…/agent.js• L22-25 extension/…/agent.js• L68-70

User flows

The surfaces share a scan and review cycle, but each one starts that cycle in a different way. The panel and sidebar can trigger a scan when an engineer engages with DevTools, while the popup starts one only after the engineer presses its scan button.

Scan lifecycle

The scan lifecycle turns a user action into findings for the inspected tab. The DevTools page can request an automatic scan when DevTools opens, and opening the panel or sidebar also requests a scan when no findings exist. The popup always uses an explicit scan action.

The main sequence is:

  1. A DevTools surface or the popup asks the extension runtime to scan a tab.
  2. The runtime makes sure the page bridge is active and sends the scan request with the saved scan preferences.
  3. The page bridge passes the request to the page detector.
  4. The detector returns findings to the runtime.
  5. The runtime stores the result for that tab, updates the browser badge, and broadcasts it to open DevTools surfaces and the popup.

This diagram shows how the user-facing surfaces share one result path.

flowchart LR
    U[Engineer action] --> S{Interface}
    S -->|DevTools opens| D[DevTools lifecycle]
    S -->|Panel or sidebar opens| P[DevTools surface]
    S -->|Scan button| X[Popup]
    D --> R[Extension runtime]
    P --> R
    X --> R
    R --> B[Page bridge and detector]
    B --> R
    R --> F[Per-tab findings and badge]
    F --> P
    F --> X
    F --> E[Page overlays]

References: extension/…/devtools.js• L21-45 extension/…/service-worker.js• L49-109 extension/…/service-worker.js• L204-247 extension/…/popup.js• L77-112 extension/…/popup.js• L132-140 extension/…/content-script.js• L21-69

Finding focus

The panel connects a finding to the inspected page in two directions. Hovering a usable finding asks the page bridge to highlight its selector. Clicking it asks the inspected page to scroll to the matching element and select it in DevTools. When the pointer returns to the page, the bridge tells the panel to clear its hover state.

The sidebar uses the reverse direction. DevTools supplies the selected element, and the sidebar asks the inspected page which known selectors match it. This lets the sidebar stay limited to the element under review while the panel keeps the complete page list.

References: extension/…/panel.js• L267-289 extension/…/panel.js• L385-409 extension/…/sidebar.js• L31-66 extension/…/content-script.js• L34-40 extension/…/content-script.js• L72-81

State coordination

The extension runtime keeps findings and overlay visibility per tab. It sends the current state to a new panel or sidebar connection, then forwards later changes to every open DevTools surface and to the popup. The popup limits its view to the active tab, so a background tab can be scanned without changing the popup’s display.

Navigation clears the old result because the page bridge no longer represents the new document. The popup also clears its local result as navigation starts or the active tab changes, then accepts a stored scan only when its URL still matches the active page. When DevTools remains open after a navigation, the runtime can scan again for a tab that was already engaged. The panel sends periodic heartbeats while it is open and recreates its runtime connection after a disconnect. Closing DevTools removes the page overlays and clears the tracked result for that DevTools session.

References: extension/…/service-worker.js• L8-37 extension/…/service-worker.js• L123-138 extension/…/service-worker.js• L165-183 extension/…/service-worker.js• L256-287 extension/…/panel.js• L15-33 extension/…/panel.js• L168-205 extension/…/popup.js• L55-89 extension/…/popup.js• L91-130

Account flow

The account flow connects the options page to the extension account service without exposing account tokens to the page or popup UI. The options page asks for status, sign-in, sign-out, or a development server change, and the account worker returns only the state needed to render the page.

The local agent allowlist follows a separate browser-local flow. The options page removes an origin from storage, and the agent reads that same list when it decides whether a site needs a new permission prompt.

References: extension/…/settings.js• L9-39 extension/…/settings.js• L42-64 extension/…/worker.js• L1-7 extension/…/worker.js• L262-275 extension/…/agent.js• L68-70

UI assets

Each surface has a small set of page, behavior, and style assets. The manifest connects the browser action to the popup and connects the DevTools entry page to the panel and sidebar. The shared extension icon identifies Impeccable in browser and DevTools chrome.

Surface assets

The asset roles are:

SurfacePage and behaviorVisual assets
DevTools entryextension/…/devtools.html, extension/…/devtools.jsicons/icon-32.png for the panel entry; panel and sidebar pages
Panelextension/…/panel.html, extension/…/panel.jsextension/…/panel.css; inline brand mark and toolbar icons for copy, scan, overlays, and settings
Sidebarextension/…/sidebar.html, extension/…/sidebar.jsextension/…/sidebar.css; compact finding and state presentation
Popupextension/…/popup.html, extension/…/popup.jsextension/…/popup.css; inline brand mark, count, copy, scan and overlay controls, and error area
Options pageextension/…/settings.html, extension/…/settings.jsShared visual tokens, account state, server field for unpacked builds, and agent-site list

The panel and sidebar load shared visual tokens with their local styles. The popup uses the same shared visual base with a compact count-and-action layout. The options page uses the same visual tokens for account and site controls. These assets keep the brand and the meaning of finding states consistent while each surface stays suited to its available space.

References: extension/manifest.json• L18-38 extension/…/devtools.js• L9-18 extension/…/panel.html• L4-34 extension/…/panel.css• L22-148 extension/…/sidebar.html• L4-12 extension/…/sidebar.css• L10-94 extension/…/popup.html• L3-38 extension/…/popup.css• L8-79 extension/…/settings.html• L3-35 extension/…/words.js• L3-15

Change checklist

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

  • Keep the message names and tab identifiers aligned between the panel, sidebar, popup, service worker, and content script. A mismatch can leave one surface with stale findings while another surface updates.
  • Preserve the finding shape used by all three surfaces, including grouped findings, selectors, page-level markers, hidden markers, detail text, and the AI tell, quality, and advisory category values.
  • Keep scan preference names and defaults aligned between panel controls, stored settings, and the runtime scan configuration.
  • When changing DevTools entry paths or UI assets, update both the manifest registration and the paths created by devtools.js.
  • When changing overlay state, keep the page-to-runtime update and runtime-to-surface broadcasts in step so the panel and popup show the same visibility state.
  • When changing finding types, update the panel’s suggested skill mapping so copied reports still give useful fix guidance.
  • Keep the options-page account actions aligned with the account worker’s allowed sender checks and response states.
  • Keep the agentSites storage key and origin format aligned between the options page and the local agent permission check.
  • Keep popup report copying tied to the active tab’s current URL so a result from an earlier document cannot be copied as the current report.

Important failure modes

TriggerConsequenceGuard
The active tab is a restricted page such as a browser page or an inaccessible local file.The popup cannot complete the scan and shows an error instead of leaving the button in a busy state.The runtime reports the injection error and gives the local-file permission hint when the URL uses file:.
A page navigation replaces the document while the old tab state remains marked as injected.A later popup scan can appear to succeed without a content listener and the surfaces can show stale findings.Navigation clears findings and injection flags before any optional DevTools rescan.
The popup remains open while the active tab changes or its URL changes.The count or copied report can refer to a different document than the one now in front.The popup clears on tab activation and navigation, and checks the current tab URL before accepting or copying a scan.
The Manifest V3 service worker stops while a panel or sidebar stays open.A long-lived surface can lose its message port and stop receiving state.The panel recreates its port after disconnect and sends heartbeats while open, so later actions can restore the connection.
A finding points to a hidden element or a page-level issue.Clicking it cannot select a useful page element.The panel marks these cases and only attaches inspection behavior to visible element findings; the sidebar excludes them.
The options page sends an account request that the worker does not accept from that page.Sign-in state does not load or an account action fails.The account worker checks that the sender belongs to the extension’s popup URL before it handles the request.
The options page and agent use different agentSites formats or keys.A site removed in settings can remain always allowed, or a saved site can cause repeated prompts.Both surfaces use the same browser-local key and validate stored web origins.

Key files

FileWhy to read it
extension/manifest.jsonDefines the DevTools entry page, options page, browser action icons, and relevant extension registrations.
extension/…/devtools.jsShows how the panel and Elements sidebar are registered and how the DevTools session starts and ends.
extension/…/panel.jsDescribes the full finding review flow, controls, settings, copying, suggested fix skills, and page-element focus.
extension/…/sidebar.jsShows how the selected Elements-panel node is matched to page findings.
extension/…/popup.jsShows the active-tab quick actions, report copying, and popup state and error handling.
extension/…/settings.jsShows account status actions and management of sites that the local agent may always use.
extension/…/words.jsDefines the shared account labels used by the options page.
extension/…/worker.jsCoordinates account status, sign-in, sign-out, server selection, and sender checks for popup pages.
extension/…/agent.jsShows how the local agent reads the always-allowed site list.
extension/…/service-worker.jsCoordinates per-tab state, scans, overlay changes, DevTools connections, and broadcasts.
extension/…/content-script.jsBridges commands and results between the extension runtime and the page detector.
extension/…/panel.html and extension/…/panel.cssDefine the panel controls, settings, finding layout, states, and DevTools presentation.
extension/…/sidebar.html and extension/…/sidebar.cssDefine the selected-element view and its compact finding and state presentation.
extension/…/popup.html and extension/…/popup.cssDefine the popup’s brand, count, copy, scan and overlay actions, and error area.
extension/…/settings.htmlDefines the options page structure for account state and agent-site settings.