ComparEdge Copilot Extension
Technical Reference Manual

01Abstract

ComparEdge Copilot is a Manifest V3 Chrome extension that recognises a SaaS or AI tool by its domain as you browse, and surfaces what the vendor's own page tends to bury: the real starting price, the annual-billing discount, one sharp hidden-cost line, key features, and cheaper or pricier alternatives. No account, no sign-in.

The extension operates on a static content script + pull model: the content script is declared in the manifest and automatically injected by Chrome into every page. Upon page load, the content script queries the background service worker for product data associated with the current domain. If a match exists and the product has not been dismissed by the user, an interactive card is rendered inside an isolated Shadow DOM container.

02Specifications

03System Architecture

The extension is composed of four primary components, each with a distinct execution context and responsibility boundary:

Manifest & Permissions

// manifest.json -- abbreviated
{
  "manifest_version": 3,
  "permissions": ["activeTab", "storage", "tabs", "alarms"],
  "host_permissions": ["<all_urls>"],
  "background": { "service_worker": "background.js" },
  "content_scripts": [{
    "matches": ["<all_urls>"],
    "js": ["content.js"],
    "run_at": "document_end"
  }]
}

Service Worker

The service worker (background.js) is the central coordinator. It handles three classes of events:

Content Script

The content script follows a pull model: instead of waiting for the background to push data, it requests data upon initialisation. This eliminates all timing-dependent race conditions inherent to the previous push-injection model.

// content.js -- initialisation sequence
(function() {
  // 1. Register message listener (CE_INIT + CE_THEME)
  chrome.runtime.onMessage.addListener((msg) => { /* ... */ });

  // 2. Pull model -- request data from background
  chrome.runtime.sendMessage({ type: 'CE_READY' }, (response) => {
    if (chrome.runtime.lastError) return;
    if (response?.product) initCard(response.slug, response.product, response.alts);
  });
})();

Popup Interface

The popup renders four tab panels. Tab state is ephemeral (resets on popup close). Product data is accessed directly from CE_DATA for the Search tab, avoiding async IPC overhead.

Data Layer

data.js is the sole source of product intelligence in the bundled extension. It defines the CE_DATA global on the globalThis / window scope depending on execution context.

// CE_DATA structure
const CE_DATA = {
  products: {
    "shopify": { n: "Shopify", r: 4.5, p: 25, f: false, cat: "website-builders",
      d: "...", pr: ["..."], co: ["..."] },
    // 507 more entries...
  },
  domainMap: {
    "shopify.com": "shopify",
    "notion.so":   "notion",
    // 462 more entries...
  },
  alternatives: {
    "shopify": [{ s: "wix", n: "Wix", r: 4.2 }, /* ... */]
  }
};

04Domain Matching Algorithm

The domain resolution algorithm performs eTLD+1 extraction with subdomain walk-up, ensuring that app.notion.so, www.notion.so, and notion.so all correctly resolve to the notion product slug.

function extractBaseDomain(hostname) {
  hostname = hostname.replace(/^www\./, '');

  // Try exact match first
  if (CE_DATA.domainMap[hostname]) return hostname;

  // Walk up subdomains: app.hubspot.com -> hubspot.com -> com
  const parts = hostname.split('.');
  for (let i = 1; i < parts.length - 1; i++) {
    const candidate = parts.slice(i).join('.');
    if (CE_DATA.domainMap[candidate]) return candidate;
  }
  return null;
}

Resolution Steps

• Strip www. prefix from hostname
• Check exact match in domainMap
• Walk up subdomain hierarchy (e.g. app.hubspot.com to hubspot.com)
• Return null if no match found (no card rendered, badge cleared)

05Injection Model

Version 1.0 adopts a static content script declaration model, superseding the previous dynamic injection approach (chrome.scripting.executeScript) which suffered from injection cache invalidation bugs and race conditions.

06Card UI & Shadow DOM

The card UI is rendered inside a Shadow DOM attached to a custom host element (id="comparedge-advisor-root") appended to document.body. This provides complete style isolation -- page CSS cannot leak in, and extension CSS cannot leak out.

// Shadow DOM initialisation
const host = document.createElement('div');
host.id = 'comparedge-advisor-root';
const shadow = host.attachShadow({ mode: 'closed' });

// CSS variables defined on #ceWrapper (not :host -- avoids all:initial conflict)
shadow.innerHTML = `
  <style>${getStyles()}</style>
  <div id="ceWrapper">
    <div class="ce-badge" id="ceBadge">...</div>
    <div class="ce-card" id="ceCard">...</div>
  </div>
`;
document.body.appendChild(host);

Card Structure

Drag & Persist

The card is freely draggable via mousedown/mousemove/mouseup listeners on the header. Position is persisted to chrome.storage.local under the ce_position key. On card initialisation, saved position is validated against the current viewport dimensions -- if out-of-bounds, the position is cleared and the card resets to its default bottom-right anchor.

// Bounds validation on position restore
const left = parseFloat(pos.left);
const top  = parseFloat(pos.top);
const maxLeft = window.innerWidth  - 340;
const maxTop  = window.innerHeight - 80;
if (left >= 0 && left <= maxLeft && top >= 0 && top <= maxTop) {
  host.style.left = pos.left; host.style.top = pos.top;
} else {
  chrome.storage.local.remove('ce_position'); // reset
}

07Card Lifecycle

States

Dismiss Flow

Restore Flow

08Theme System

The extension supports three theme modes: dark (default), light, and auto (follows prefers-color-scheme). Theme state is applied to two distinct scopes:

Real-time Theme Propagation

When the user changes theme in the popup Settings tab, applyTheme() updates the popup DOM and simultaneously sends a CE_THEME message to the active tab content script, which then calls applyCardTheme(). This ensures both surfaces update without requiring a page reload.

// popup.js -- theme change handler
function applyTheme(theme) {
  document.documentElement.classList.remove('theme-dark', 'theme-light');
  const isDark = theme === 'dark' || (theme === 'auto' && matchMedia('(prefers-color-scheme: dark)').matches);
  document.documentElement.classList.add(isDark ? 'theme-dark' : 'theme-light');
  chrome.tabs.query({ active: true, lastFocusedWindow: true }, (tabs) => {
    if (tabs[0]?.id)
      chrome.tabs.sendMessage(tabs[0].id, { type: 'CE_THEME', theme }).catch(() => {});
  });
}

09Remote Sync

The extension refreshes its catalog every 24 hours so pricing stays current without shipping a new version. The endpoint returns the same payload shape as the bundled CE_DATA, built by the same server module (extensionPayload.js) that generates the bundled file, so the two can never drift.

10Security Model

Privacy Architecture

The extension stores no personal data and sends no telemetry from your browser. Domain matching, card rendering, settings and dismissals all run locally. It makes exactly one automatic network request:

• GET https://comparedge.com/extension-sync.json — a read-only data refresh every 24 hours. It fetches public product data and sends nothing about you.

When you click through to comparedge.com, the link carries ?utm_source=comparedge-copilot. The site records that referral — which product, which surface, and the country resolved at the edge — in its extension_events table, so we can see what the extension is actually used for. This is ordinary referral attribution, the same as any campaign link: no user identifier, no cross-site profile, and nothing about your browsing leaves the machine on its own.

XSS Mitigation

Every string from the data payload (product names, descriptions, features, hooks) is HTML-encoded by a sanitize function before it touches innerHTML:

function s(str) {
  if (typeof str !== 'string') return '';
  return str
    .replace(/&/g, '&')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;')
    .replace(/"/g, '&quot;')
    .replace(/'/g, '&#39;');
}

This ensures that even a compromised sync endpoint cannot inject executable HTML or JavaScript into the card UI.

Content Security Policy

The extension enforces a strict CSP for extension pages:

"script-src 'self'; object-src 'self'"

This prohibits inline scripts, eval(), remote script loading, and all plugin objects within the popup and options pages. Content scripts run in an isolated world and are not subject to the page own CSP.

Shadow DOM Isolation

The card UI uses a closed Shadow DOM (attachShadow({ mode: 'closed' })). This means:

• Page JavaScript cannot access the shadow root via element.shadowRoot
• Page CSS selectors cannot target elements inside the shadow tree
• Extension CSS cannot inadvertently style page elements
• User scripts and page-level XSS cannot tamper with the card UI

11Storage Schema

All persistent state is stored in chrome.storage.local. The following keys are used:

12Message API

13Settings API

14Product Data Schema

Each product entry in CE_DATA.products conforms to the following shape:

Alternative entries in CE_DATA.alternatives[slug]:

15Performance

16Changelog

All version history, release notes, and architectural changes are tracked in the extension changelog. Each entry documents new features, bug fixes, security updates, and data layer changes with exact dates and version numbers.

The changelog follows Semantic Versioning: MAJOR.MINOR.PATCH. Breaking changes increment MAJOR, new features increment MINOR, bug fixes increment PATCH.