browser-verification

# Browser Verification Skill Rendered UI proof for Coop. Use this before claiming that a visual, interaction, or browser-runtime fix works. This skill does not replace tests. It catches the things static checks miss: blank screens, clipped popup content, console errors, broken focus, missing assets, and sidepanel layout regressions. --- ## Activation | Trigger | Action | |---------|--------| | UI files changed | Run rendered browser verification before reporting done | | Popup or sidepanel behavior changed | Verify extension surface at realistic dimensions | | CSS, token, layout, or animation changed | Capture screenshot proof and inspect console | | Receiver/PWA flow changed | Verify app route and responsive state | | Visual QA requested | Use Playwright or browser automation and report proof limits | ## Tool Selection | Tool | Use For | Proof Limits | |------|---------|--------------| | Codex Browser / Browser Use | Local app routes, receiver PWA preview routes, docs, public pages without sign-in, screenshots, and responsive checks. | Cannot load unpacked extension UI, signed-in Chrome state, browser extensions, or OS prompts. | | Playwright | Repeatable checks for Browser-covered flows, layout invariants, routing, and regression gates. | Does not replace real extension-card, toolbar popup grant, installed PWA, or permission-prompt evidence. | | Codex Chrome extension | Signed-in Chrome/profile state and browser tasks that need the user's real Chrome context. | Prefer Browser for unauthenticated localhost routes. | | Computer Use / real headed Chromium | Unpacked extension popup/sidepanel, extension-card errors, `activeTab`, screenshot capture, installed PWA behavior, OS/browser prompts, and cross-app GUI flows. | Keep tasks narrow and record app/browser/profile because it can affect state outside the repo. | ## Scope Selection | Surface | Start Command | Primary Checks | |---------|---------------|----------------| | App / receiver PWA | `bun dev:app` | Routes render, responsive layout, console clean | | Extension build | `cd packages/extension && bun run build` | MV3 output exists, no build/runtime errors | | Extension dev | `bun dev:extension` | Popup/sidepanel render in Chromium | | API-backed flows | `bun dev:api` | Pairing, sync, receiver handoff | | Docs | `bun run docs:dev` | Docs route renders under Node 22/mise | Prefer the smallest surface that proves the change. Use full E2E only when the user path crosses surfaces. --- ## Verification Workflow ### 1. Identify the Rendered Surface Map changed files to the UI surface: - `packages/extension/src/views/Popup/**` -> popup - `packages/extension/src/views/Sidepanel/**` -> sidepanel - `packages/app/src/**` -> app or receiver PWA - `packages/shared/src/styles/**` -> app and extension downstream checks - `docs/**` -> docs site If the changed file is shared styling or a shared UI contract, verify at least one downstream consumer. ### 2. Run the Right Local Target Use the lightest target first: ```bash cd packages/extension && bun run build bun dev:app bun dev:api ``` For automated coverage: ```bash bun run test:visual bun run test:e2e:popup bun run test:e2e:extension bun run test:e2e:app ``` ### 3. Inspect the Browser Use available browser automation or manual Chrome inspection to verify: - The target route or extension surface is not blank. - Console has no new errors. - Primary actions are clickable with mouse and keyboard. - Focus order is coherent. - Text fits at narrow and standard widths. - Loading, empty, error, and success states still render when relevant. - Animations respect `prefers-reduced-motion` when touched. For popup checks, verify the 400px fixed-width constraint. For sidepanel checks, verify narrow and wider panel widths when layout changed. ### 4. Capture Proof Report proof in the final or handoff: ```markdown ### Browser Verification - Surface: popup / sidepanel / app / docs - Tool: Browser / Playwright / Chrome / Computer Use / manual headed browser - Target: http://127.0.0.1:3001/... or extension dev window - Checks: rendered, primary action, console, responsive width - Evidence: screenshot path or Playwright command - Limits: anything not covered ``` Never say "looks good" without naming what rendered and what was checked. --- ## Common Failure Modes | Symptom | Likely Cause | Next Check | |---------|--------------|------------| | Blank popup | Extension build/runtime error | Inspect extension console and `cd packages/extension && bun run build` | | Sidepanel clips content | Fixed width or missing container constraints | Test 300px and 800px widths | | Click works, keyboard fails | Non-semantic interactive element | Use `ui-compliance` checks | | Test passes, visual broken | Assertion missed layout or asset state | Add screenshot or DOM visibility assertion | | App works, extension fails | MV3/runtime mismatch | Check service worker constraints and extension console | ## Related Skills - `ui-compliance` -- Accessibility, focus, responsive, and reduced-motion checks. - `testing` -- Vitest and Playwright test strategy. - `design` -- Coop visual language and surface-specific interaction rules. - `debug` -- Root cause investigation when rendered proof fails.