Clear11y

Extracts static builds from ZIP archives and serves them over an ephemeral HTTP server bound to port 0 (kernel-assigned). The server runs in a daemon thread with a 5-second join timeout on shutdown. BLOCKED_URL_PATTERNS aborts requests to analytics and tracking domains for deterministic scans.

IS_FOCUS_VISIBLE_SCRIPT snapshots 8 computed style properties as primitive strings before calling element.focus({ focusVisible: true }), then compares after values. Detects missing indicators across 5 categories: outline, box-shadow, border, background-color, and text-decoration. The focusVisible: true option triggers :focus-visible UA styles, matching what keyboard users actually see.

Simulates full Tab traversal (up to 150 keypresses), recording each focused element's selector, role, accessible name, and bounding box. Injects an SVG overlay with magenta numbered circles (r=14) connected by lines showing exact tab order. Captures a full-page screenshot so you can see at a glance if navigation is out of order.

Presses Tab 20 times from a clean page and tracks focus history. If the same element appears 3+ times consecutively, that indicates a focus trap. Reported as a critical severity violation mapped to WCAG 2.1.2 (No Keyboard Trap).

Before any real scan, _self_validate() creates an inline test page with three buttons: one with proper outline focus, one with outline: none, and one with box-shadow. The validator checks that IS_FOCUS_VISIBLE_SCRIPT correctly distinguishes them. If validation fails, every subsequent scan logs a warning. This caught a real regression when a Playwright version changed focusVisible behavior.

I eliminated browser cold starts by sharing one Chromium process across all pages and creating isolated BrowserContexts per page. Each context resets cookies and storage without the ~500ms browser launch cost. The axe engine and keyboard engine use separate Playwright instances because they have different lifecycle requirements.

Captures violations with red-highlighted CSS overlays injected via page.evaluate(). Default highlight is outline: 4px solid #ff0000 with box-shadow. Up to 4 elements per violation (configurable via A11Y_SHOT_MAX_TARGETS), with overlapping elements merged into single contextual screenshots.

Penalty weights: critical=40, serious=20, moderate=5, minor=1. Score is 100 minus the sum of penalties, capped at 0. Keyboard violations count too, with focus traps and unreachable elements rated critical, poor indicators rated serious. Grades: 90+ is A+, 80+ is A, 70+ is B, 60+ is C, 50+ is D, below 50 is F.

Two-pass path validation: rejects absolute paths and '..' components before os.path.normpath(), then checks again after normalization (which can introduce traversal from safe-looking inputs). Final guard via os.path.commonpath() on resolved absolute paths. Zip Bomb protection reads uncompressed sizes from the ZIP central directory and aborts at 500 MB before any bytes hit disk.

For URL scans, _validate_public_http_url() resolves hostnames via socket.getaddrinfo() and requires every resolved IP to pass ipaddress.is_global. Blocks RFC 1918, loopback, and link-local addresses. Localhost is also blocked by name before DNS lookup to catch trivial bypasses. ZIP scans restrict Playwright navigation to localhost origins only.

POST endpoints return HTTP 202 with a job ID immediately. Scans run in asyncio background tasks offloaded via asyncio.to_thread() to avoid blocking the uvicorn event loop. Jobs expire after a configurable retention period (default 24 hours) and get cleaned up at startup and on a periodic schedule.

Composite action with 4 steps: setup Python, install package, build Docker image, run scan. Outputs 7 variables including total-violations, critical-violations, keyboard-violations, and scan-status. The fail-on-violations input exits 1 to block deployment when thresholds are exceeded. Reports upload as build artifacts automatically.