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 / browser-extension

Browser extension product

The Impeccable browser extension connects a live web experience to local design analysis and guided browser walks. It lets an engineer inspect a page, review findings in browser tools, and watch an Impeccable persona or local agent work through a chosen site. See Extension page integration, DevTools and popup interfaces, and Account and guided inspection walks for the child pages.

References: extension/manifest.json• L1-40 extension/STORE_LISTING.md• L23-29 extension/STORE_LISTING.md• L76-80

Product workflow

The extension supports two related workflows. A scan finds design problems in the page that is open. A guided walk lets an Impeccable persona or the engineer’s local agent inspect and act in a controlled browser tab.

Page analysis

Page analysis turns the current rendered page into findings that an engineer can review in context. The rules run locally. The extension shows the result through page overlays and browser review surfaces.

The analysis loop is:

  1. The engineer opens the Impeccable surface or chooses Scan page.
  2. The extension captures the rendered page and evaluates its design rules.
  3. Findings appear as overlays and as grouped review items.
  4. The engineer focuses a finding, inspects its element, copies the result, or changes a rule and scans again.

Findings cover AI design tells, general quality problems, and accessibility concerns. Element findings can point to a matching page element. Page-level findings remain reviewable without an element target. See Extension page integration for the page boundary and overlay flow.

References: extension/STORE_LISTING.md• L28-74 extension/…/popup.html• L14-38 extension/…/popup.js• L47-75

Guided browser walks

A guided browser walk is a session in which a remote Impeccable persona or a local agent observes a selected web experience and carries out browser actions. The walk gives the person a live record in the side panel and keeps the browser under a clear set of limits.

The walk moves through these stages:

  1. The Impeccable app or the local agent requests a walk for a page and task.
  2. The extension accepts a trusted hand-off and connects the session to its browser driver.
  3. The driver opens or adopts one tab and reports page state, steps, questions, and results.
  4. The person can pause, take over, answer a consent question, hand the tab back, or stop the walk.
  5. The session ends with a result page or a local agent session that leaves the tab with the person.

The remote walk uses the person’s selected persona and task. The local agent is reached through the Impeccable CLI and asks the person before it uses a new site unless that site is already allowed. See Account and guided inspection walks for account, persona, and walk behavior.

References: extension/…/handoff.js• L70-86 extension/…/link.js• L139-198 extension/…/agent.js• L237-272

Runtime architecture

The extension separates browser coordination from page access and from guided-walk control. Its background worker joins the detector runtime, the walk runtime, and the account runtime so the user-facing surfaces share one browser session without sharing page code.

Background coordination

The background runtime is the extension’s central coordinator. It routes scan requests, tab state, account requests, journey hand-offs, side-panel commands, and browser lifecycle events to the part that owns each concern.

The Chrome background entry point loads three product areas:

Product areaRole
Detector runtimeInspect the current page and keep scan findings for its tab
Walk runtimeConnect a guided session to one browser tab and enforce its controls
Account runtimeSign in, refresh the account session, load personas, and start walks

Chrome opens the side panel from the toolbar. Firefox keeps the compact popup path for scan controls. The same extension can therefore expose a full guided-session surface on Chrome while retaining a small analysis surface on platforms without a side panel.

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

Analysis runtime

The analysis runtime measures the live page through a page bridge and evaluates a local rule core outside the page. This split lets the extension inspect pages with strict content policies without asking the page to run the rule engine.

The page bridge sends page data to the rule core, answers live questions such as element hit tests, and draws the returned findings. The service worker keeps the result tied to the tab. A shared report format keeps categories, copied findings, and skill suggestions consistent across the review surfaces.

References: extension/…/service-worker.js• L1-24 extension/…/content-script.js• L1-17 extension/…/findings-report.js• L1-127

Walk runtime

The walk runtime connects a trusted hand-off from an Impeccable page to a single browser tab. A WebSocket carries the session messages. The driver reports what happens in the tab while the guard and control layers decide what the walk may do.

The walk runtime has four product roles:

RoleResponsibility
Hand-off and linkAccept a walk only from an allowed Impeccable page or account request
DriverRead the tab, perform the requested browser actions, and report progress
Guard and network holdKeep navigation, writes, downloads, and tab access within the walk’s rules
Control and viewApply pause, take-over, consent, stop, and result state for the panel and badge

References: extension/…/worker.js• L1-16 extension/…/handoff.js• L114-179 extension/…/guard.js• L1-38 extension/…/control.js• L77-115

User-facing surfaces

The extension presents the same product state through surfaces for detailed review, quick analysis, account setup, and guided work. Each surface serves a different moment in the engineer’s workflow.

DevTools and popup surfaces

DevTools is the detailed analysis surface. It groups findings, links them to the Elements panel, controls overlays, and exposes scan settings. The popup is the compact surface for the active tab. It shows a finding count and supports scanning, copying, and overlay visibility without opening the full review surface.

In Chrome, the toolbar action opens the side panel. The side panel is the shared home for scan state, account state, guided walks, and questions from a local agent. The platform-specific popup remains useful where a side panel is not available. See DevTools and popup interfaces for the detailed interface contract.

References: extension/…/popup.html• L14-38 extension/…/popup.js• L77-112 extension/…/toolbar.js• L12-20

Account and settings surfaces

The account surface lets a person sign in to an Impeccable server and see the account used by the extension. Sign-in uses a browser account flow. The background runtime keeps the session and returns account facts to the popup or side panel without exposing tokens to page code.

The settings surface also lists sites that the person has chosen to always allow for their local agent. Removing a site changes where later agent sessions may work. Development builds can point the account flow at a staging or local server. Store builds use the production service and omit development-only account features.

References: extension/…/flow.js• L1-26 extension/…/session.js• L1-14 extension/…/worker.js• L21-72 extension/…/settings.js• L28-64 extension/…/build.js• L1-4

Walk status surfaces

The side panel is the main control surface for a guided walk. It shows the selected persona, task, steps, checks, questions, pauses, and outcome. The in-page badge gives the person a visible status and a fast way to answer or stop while the panel is closed.

The walk can pause at a sign-in page or before a meaningful write. During a take-over, the person uses the tab directly. The walk resumes only after the person hands control back and the extension confirms that the tab is safe to use again.

References: extension/…/view.js• L7-13 extension/…/control.js• L121-153 extension/…/badge.js• L180-191

The extension engages with ordinary web pages only when the person asks for a scan or starts a walk. It does not need to keep the analysis bridge active on every page.

For analysis, navigation clears findings that belong to the old document. A full navigation or a single-page-app route change can start a new scan only when the relevant surface is already engaged. The popup remains user-triggered. A walk has a different lifecycle: its connection and one-tab state end when the tab, socket, or guarded session ends.

The account check-in lifecycle is separate from page analysis. A signed-in Pro account can receive notices for walks waiting for the person to start. Signing out clears those notices and stops further check-ins.

References: extension/…/popup.js• L91-120 extension/…/waiting.js• L1-6 extension/…/waiting.js• L78-115 extension/…/link.js• L117-137

Data and trust boundaries

The extension has two data paths with different privacy rules. A normal page scan stays in the browser. A guided walk sends only the selected walk’s page data to the Impeccable service because the service must drive the session and build its result.

The walk boundary is deliberately narrow. A remote walk uses one tab, limits the allowed origins, holds writes until the server or person opens them, and stops at sign-in pages. Password, card, and one-time-code fields are not read. Screenshots are taken only after sensitive fields are covered. A local agent adds a person-controlled site permission and does not expose other tabs to the agent.

The hand-off also prevents an ordinary web page from starting a walk. Only an approved Impeccable page or the account worker can create the connection data that the walk runtime accepts.

References: extension/STORE_LISTING.md• L65-74 extension/STORE_LISTING.md• L102-118 extension/…/guard.js• L12-38 extension/…/signin.js• L1-19 extension/…/driver.js• L638-689

Build and distribution model

The repository supports a richer unpacked build and a reduced store build. The unpacked build can use account sign-in, local or staging hosts, guided walks, and the local agent. The store build focuses on local page analysis and the supported production extension surface.

The build choice affects both the manifest permissions and which files are packaged. Product changes must therefore keep the build description, store listing, manifest, and runtime feature checks aligned.

References: extension/…/build.js• L1-4 extension/manifest.json• L7-25 extension/STORE_LISTING.md• L11-18

Change checklist

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

  • Changes to the manifest or build flags must keep Chrome, Firefox, unpacked, and store entry points consistent.
  • Changes to account server selection must keep OAuth metadata checks, stored sessions, walk sockets, and local host pairing aligned.
  • Changes to a walk hand-off must stay aligned with the Impeccable app’s outing payload, socket address, ticket rules, persona data, and allowed origins.
  • Changes to the walk state must update the side panel, badge, account worker answers, result links, and socket reconnect behavior together.
  • Changes to navigation or write rules must preserve the one-tab boundary and the difference between remote walks and the person’s local agent.
  • Changes to secret-field detection must stay aligned across sign-in pauses, page helpers, screenshots, film frames, and agent reads.
  • Changes to agent site permissions must update the settings list and the permission checks that run before a new site opens.
  • Changes to scan results must preserve tab ownership, URL validity, overlay state, popup counts, DevTools grouping, and copied report text.

Important failure modes

TriggerConsequenceGuard
The browser refuses page injection or the page cannot be scannedThe analysis surface shows an error and no resultThe background runtime reports the failure and keeps the scan user-triggered
A page navigates before a result is copiedThe old result is cleared or copying is refusedScan state carries the page URL and is checked against the active tab
A walk hand-off has the wrong origin, socket, ticket, or shapeThe walk does not startThe hand-off reader accepts only approved pages and validated fields
A walk loses its socket while the debugger controls a tabThe walk fails and the debugger is releasedThe link layer retries only while waiting for a tab and closes the walk after control begins
A walked page leaves its allowed site or sends an unapproved writeNavigation or the request is blockedThe guard and network hold enforce site and write limits
A sign-in or secret field appears during a walkThe walk pauses and stops sharing page dataFixed sign-in checks, secret-field covers, and person-controlled continuation protect the tab
The service worker restarts during a walk or account actionThe current connection or request may be lostSession state, hand-off state, and account records support safe recovery or fail closed
A person removes an always-allowed agent site during a sessionThe local agent session endsSettings changes are observed and revoke the active site allowance

Key files

FileWhy to read it
extension/manifest.jsonDefines the browser permissions, side panel, DevTools page, options page, and app-only content scripts
extension/…/chrome-worker.jsShows how the detector, walk, and account runtimes enter the Chrome background worker
extension/…/service-worker.jsShows scan coordination, page injection, local rule-core startup, and per-tab state
extension/…/content-script.jsShows the page-facing analysis boundary, staged scan flow, and overlays
extension/…/findings-report.jsKeeps finding groups, skill suggestions, and copied report text consistent
extension/…/worker.jsShows account messages, persona loading, walk starts, and the side-panel connection
extension/…/session.jsShows the account session boundary and the high-level account and journey data contract
extension/…/waiting.jsShows how signed-in Pro accounts receive waiting-journey notices
extension/…/popup.jsShows the compact scan, copy, overlay, and active-tab behavior
extension/…/settings.jsShows account controls and local agent site permissions
extension/…/handoff.jsDefines the trusted page-to-extension boundary for guided walks
extension/…/link.jsShows walk connection, ticket use, reconnect, and current-tab adoption
extension/…/worker.jsShows the walk socket and browser protocol entry point
extension/…/guard.jsDefines the site, tab, navigation, write, download, and fail-closed limits
extension/…/control.jsConnects person controls and consent questions to the walk state
extension/…/agent.jsShows the local agent boundary, site permission flow, and browser tools
extension/…/page-helpers.jsDefines the fixed page reads and actions that a guided walk can run
extension/…/signin.jsDefines the sign-in and sensitive-field signals that pause a walk
extension/…/view.jsDefines the shared walk state shown by the panel and badge
extension/…/badge.jsShows the in-page status and consent surface
extension/STORE_LISTING.mdStates the user-facing product promise, privacy boundary, and store-versus-unpacked scope