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:
- The engineer opens the Impeccable surface or chooses Scan page.
- The extension captures the rendered page and evaluates its design rules.
- Findings appear as overlays and as grouped review items.
- 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:
- The Impeccable app or the local agent requests a walk for a page and task.
- The extension accepts a trusted hand-off and connects the session to its browser driver.
- The driver opens or adopts one tab and reports page state, steps, questions, and results.
- The person can pause, take over, answer a consent question, hand the tab back, or stop the walk.
- 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 area | Role |
|---|---|
| Detector runtime | Inspect the current page and keep scan findings for its tab |
| Walk runtime | Connect a guided session to one browser tab and enforce its controls |
| Account runtime | Sign 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:
| Role | Responsibility |
|---|---|
| Hand-off and link | Accept a walk only from an allowed Impeccable page or account request |
| Driver | Read the tab, perform the requested browser actions, and report progress |
| Guard and network hold | Keep navigation, writes, downloads, and tab access within the walk’s rules |
| Control and view | Apply 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
Navigation and engagement lifecycle
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
| Trigger | Consequence | Guard |
|---|---|---|
| The browser refuses page injection or the page cannot be scanned | The analysis surface shows an error and no result | The background runtime reports the failure and keeps the scan user-triggered |
| A page navigates before a result is copied | The old result is cleared or copying is refused | Scan state carries the page URL and is checked against the active tab |
| A walk hand-off has the wrong origin, socket, ticket, or shape | The walk does not start | The hand-off reader accepts only approved pages and validated fields |
| A walk loses its socket while the debugger controls a tab | The walk fails and the debugger is released | The 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 write | Navigation or the request is blocked | The guard and network hold enforce site and write limits |
| A sign-in or secret field appears during a walk | The walk pauses and stops sharing page data | Fixed sign-in checks, secret-field covers, and person-controlled continuation protect the tab |
| The service worker restarts during a walk or account action | The current connection or request may be lost | Session state, hand-off state, and account records support safe recovery or fail closed |
| A person removes an always-allowed agent site during a session | The local agent session ends | Settings changes are observed and revoke the active site allowance |
Key files
| File | Why to read it |
|---|---|
| extension/manifest.json | Defines the browser permissions, side panel, DevTools page, options page, and app-only content scripts |
| extension/…/chrome-worker.js | Shows how the detector, walk, and account runtimes enter the Chrome background worker |
| extension/…/service-worker.js | Shows scan coordination, page injection, local rule-core startup, and per-tab state |
| extension/…/content-script.js | Shows the page-facing analysis boundary, staged scan flow, and overlays |
| extension/…/findings-report.js | Keeps finding groups, skill suggestions, and copied report text consistent |
| extension/…/worker.js | Shows account messages, persona loading, walk starts, and the side-panel connection |
| extension/…/session.js | Shows the account session boundary and the high-level account and journey data contract |
| extension/…/waiting.js | Shows how signed-in Pro accounts receive waiting-journey notices |
| extension/…/popup.js | Shows the compact scan, copy, overlay, and active-tab behavior |
| extension/…/settings.js | Shows account controls and local agent site permissions |
| extension/…/handoff.js | Defines the trusted page-to-extension boundary for guided walks |
| extension/…/link.js | Shows walk connection, ticket use, reconnect, and current-tab adoption |
| extension/…/worker.js | Shows the walk socket and browser protocol entry point |
| extension/…/guard.js | Defines the site, tab, navigation, write, download, and fail-closed limits |
| extension/…/control.js | Connects person controls and consent questions to the walk state |
| extension/…/agent.js | Shows the local agent boundary, site permission flow, and browser tools |
| extension/…/page-helpers.js | Defines the fixed page reads and actions that a guided walk can run |
| extension/…/signin.js | Defines the sign-in and sensitive-field signals that pause a walk |
| extension/…/view.js | Defines the shared walk state shown by the panel and badge |
| extension/…/badge.js | Shows the in-page status and consent surface |
| extension/STORE_LISTING.md | States the user-facing product promise, privacy boundary, and store-versus-unpacked scope |