Chrome Verify Checks

---
name: chrome-verify-checks
description: Use when verifying a chrome-extension/ change before reporting done. The canonical 7-check list (build → Service Worker vm.createContext compat → manifest sanity → per-site content-script DOM contract → message-passing trace → test suite → manual-load checklist) + verdict rules. chrome-extension/ is a strong-guard sub-context the maintainer cannot easily verify (MV3 SW quirks, per-site content-script breakage). Load when invoking chrome-verify or after any change in chrome-extension/. Triggers on chrome extension check, SW compatibility, MV3 check, content script behavior, extension load check.
---

# Chrome extension verification — 7 checks + manual-load checklist

`chrome-extension/` is a **strong-guard** sub-context — a frontend maintainer cannot easily catch MV3 service-worker quirks or per-site content-script breakage. This skill is the canonical verification: prove or disprove that the extension still loads, still talks across its boundaries, and still works on each target site — with real evidence.

You are a **fresh-context critic** when you load this: you did NOT make the change and you do NOT assume it works. **Falsify.**

## Setup

1. From `git diff --name-only`, confirm the change is in `chrome-extension/`.
2. Read the sub-context's own guide (TDD entry) and the manifest `chrome-extension/manifest.json` for the current permissions / matches / background entry.
3. Read `chrome-extension/shared/` for the message-passing protocol shape.

## The 7 checks (run every one — do not skip)

1. **Build the extension** — `cd chrome-extension && npm run build:dev`. Capture build output. Any error / warning = finding.

2. **Service Worker compat (`vm.createContext`)** — there is no dedicated sw-compat script in this repo. Inspect the SW entry from `chrome-extension/manifest.json` `background.service_worker`, then grep the entry file + its transitive imports for DOM-tied refs (`window.`, `document.`, `XMLHttpRequest`, `localStorage`) and for modules known to break under MV3 SW (axios with default adapter, any `node:*` import, anything pulling in `jsdom`). Any DOM-tied ref in the SW transitive closure = blocking finding. A `ReferenceError: window is not defined` at SW boot (visible from `chrome://extensions` on manual load) is the runtime symptom.

3. **Manifest sanity** — verify `manifest_version: 3`, `background.service_worker` path resolves to a real built file in `dist/`, every `host_permissions` entry is actually used by code (grep), every `matches` URL pattern resolves to an existing content-script file.

4. **Per-site content-script DOM contract** — for each target site the extension supports, grep the selector strings the content script depends on. If a selector is missing in the live DOM, the script silently no-ops on that site. List each selector + the file:line that owns it + the last-verified date if recorded. If a selector cannot be verified, flag it as CANT-VERIFY — manual browser load required by the maintainer.

5. **Message-passing trace** — for any new or changed `chrome.runtime.sendMessage` / `chrome.tabs.sendMessage` / `chrome.runtime.onMessage` handler, confirm both ends exist: a `sendMessage` without an `onMessage` listener for that type is broken; same for the reverse. Trace each message type end to end.

6. **Test suite** — `npm test` from `chrome-extension/`. Pass/fail counts.

7. **Manual-load checklist** — produce the exact step list the maintainer must run in Chrome (`chrome://extensions` → load unpacked from `dist/` → open each target site → confirm content script ran). The maintainer has to do this themselves; your job is to leave them a checklist they can run in <2 min, not a vague "test it in browser".

## Verdict rules — pick exactly 1 of 3 (all first-class)

- **PASS** — all 7 checks passed including the maintainer-confirmed manual-load checklist.
- **FAIL** — specific check(s) failed. List each with `file:line` and the failing evidence.
- **CANT-VERIFY** — manual-load is the only path to confirm a check and the maintainer has not run it yet. First-class verdict; do NOT default to "PASS (conditional)".

## Output (BLUF header first)

- **Conclusion**: one of the 3 above (+ one-line reason for CANT-VERIFY).
- **Check results** — table: item / PASS/FAIL/CANT-VERIFY / evidence (build output, selector match count, message-trace file:line, manual-load step result).
- **Defects** — every gap with `file:line`. Per-site silent no-ops are blocking.
- **Manual verification checklist** — concrete steps in `chrome://extensions`, exact URLs to open, exact DOM signals to look for. ≤ 2 min for the maintainer to run.

## Constraints (strong guard)

- Do NOT report "PASS" if any check could not be run.
- Build green is necessary but not sufficient — per-site content-script behavior requires either a real DOM snapshot or the maintainer's manual load.
- "Render ≠ works" — a passing build + clean console without a real selector match on the target site = CANT-VERIFY, not "PASS".
- Real prod hostnames in fixtures BANNED — use mock fixtures.
- **Citation-truth**: any file/contract you cite must be confirmed to exist via grep/read before it grounds a claim; a green test alone ≠ a verdict.