{"description":"Structured browser visual QA contract for screenshot capture, viewport checks, layout overflow checks, visible headings, and report evidence.","objective":"Give a future agent enough structure to start from the main URL and understand how to inspect, plan, build, validate, and improve a serious website without needing prior chat context.","browser_visual_qa":{"objective":"Prove desktop and mobile rendering quality with reproducible browser checks and screenshot evidence.","why":"Static route, SEO, and schema checks do not prove that text fits, headings are visible, layouts avoid horizontal overflow, or pages are usable at mobile and desktop widths.","command":"npm run qa:browser","reportPath":"reports/browser/browser-visual-report.json","screenshotDirectory":"reports/browser/screenshots/","baselineDirectory":"tests/browser/baselines/","diffDirectory":"reports/browser/diffs/","baselineUpdateCommand":"QA_UPDATE_BASELINES=1 npm run qa:browser","viewports":[{"id":"desktop","width":1440,"height":1000,"why":"Catches wide-layout hierarchy, card/grid, and navigation issues."},{"id":"mobile","width":390,"height":844,"why":"Catches common phone-width wrapping, clipping, overflow, and navigation issues."}],"routes":[{"path":"/","why":"Main agent entry and first-viewport orientation."},{"path":"/agent-start/","why":"Agent onboarding path."},{"path":"/repo-map/","why":"File-system discovery path."},{"path":"/standards/","why":"Specification mapping path."},{"path":"/workflows/","why":"Execution workflow path."},{"path":"/examples/","why":"Pattern/example discovery path."},{"path":"/copy-lab/","why":"Conversion copy training and weak/strong example path."},{"path":"/fixtures/page-patterns/","why":"Concrete page-pattern route fixture discovery path."},{"path":"/fixtures/design-system/","why":"Concrete design-system fixture discovery path."},{"path":"/qa-contract/","why":"Quality contract explanation path."},{"path":"/demo/brightline/","why":"Canonical demo homepage proving the playbook-built entity summary renders correctly."},{"path":"/demo/brightline/services/","why":"Demo service-offer page rendering check."},{"path":"/demo/brightline/service-areas/","why":"Demo service-area detail page rendering check."},{"path":"/demo/brightline/proof/","why":"Demo proof page rendering check."},{"path":"/demo/brightline/contact/","why":"Demo contact/conversion page rendering check."},{"path":"/demo/logpilot/","why":"SaaS demo homepage with the dark LogPilot brand tokens."},{"path":"/demo/logpilot/product/","why":"SaaS demo product page rendering check."},{"path":"/demo/logpilot/use-cases/","why":"SaaS demo use-case page rendering check."},{"path":"/demo/logpilot/integrations/","why":"SaaS demo integrations page rendering check."},{"path":"/demo/logpilot/comparison/","why":"SaaS demo comparison page rendering check."}],"checks":[{"id":"screenshot-capture","severity":"critical","method":"Capture full-page PNG screenshots for every configured route and viewport.","passCriteria":"Every route/viewport pair has a screenshot path in the report.","failCriteria":"Any screenshot is missing or the browser cannot render a route."},{"id":"visible-heading","severity":"critical","method":"Evaluate the DOM for exactly one visible H1 per route.","passCriteria":"Every checked page has exactly one visible H1.","failCriteria":"A checked page has no H1, multiple H1s, or a hidden H1."},{"id":"horizontal-overflow","severity":"critical","method":"Compare document scroll width and element bounding boxes against viewport width.","passCriteria":"No document or visible element extends beyond the viewport.","failCriteria":"Document or visible elements create horizontal overflow."},{"id":"text-clipping","severity":"warning","method":"Compare text-bearing element scroll width against client width.","passCriteria":"No likely clipped text is detected.","failCriteria":"Potential clipping is recorded as a warning for review."},{"id":"visual-diff-baseline","severity":"critical","method":"Compare every route/viewport screenshot against its committed baseline under tests/browser/baselines/ with pixelmatch; intentional changes are accepted via QA_UPDATE_BASELINES=1. A synthetic mutated-screenshot control must always register as different.","passCriteria":"Every screenshot matches its baseline within the documented diff ratio, and the mutation control detects changed pixels.","failCriteria":"A screenshot differs beyond the diff ratio or changes dimensions without a baseline update, or the diff engine fails its negative control. Failures cite route, viewport, baseline path, and a saved diff image."},{"id":"keyboard-focus-navigation","severity":"critical","method":"Tab through each desktop route, recording distinct focus stops and whether each focused element shows a visible outline or box-shadow indicator.","passCriteria":"Every route exposes at least two distinct keyboard focus stops and focused elements have visible indicators.","failCriteria":"A route is not keyboard-operable (fewer than two focus stops). Stops without visible indicators are warnings."},{"id":"axe-accessibility","severity":"critical","method":"Run axe-core with the WCAG 2.0/2.1/2.2 A+AA and best-practice tag sets on every route and viewport.","passCriteria":"No critical or serious axe violations on any route/viewport.","failCriteria":"Critical or serious violations fail with rule IDs and sample node targets; moderate/minor violations are warnings."}],"passCriteria":["Browser launches successfully.","Every configured route renders at every configured viewport.","Screenshots are saved under reports/browser/screenshots/.","The JSON report is saved at reports/browser/browser-visual-report.json.","No critical visual findings are present."],"warningCriteria":["Potential text clipping is present but does not create document overflow.","A screenshot exists but needs human visual review before launch.","The route passes local browser checks but has not been checked against production assets."],"failCriteria":["Browser cannot launch.","A route fails to render.","A configured screenshot is missing.","A page has missing/hidden/multiple H1s.","A page or visible element overflows horizontally.","A screenshot drifts from its committed baseline without QA_UPDATE_BASELINES=1.","A route is not keyboard-operable.","axe-core reports critical or serious accessibility violations.","The visual-diff mutation control fails to detect changed pixels."],"objectiveAlignment":"Adds the visual evidence layer needed before this agent-facing system can support design-system work or launch handoffs."}}