Skip to content

davepoon/buildwithclaude / plugins/all-skills/skills/launch-check

launch-check

Flagged

Passive pre-launch report card for a live URL of an app or site built with AI (Lovable, Bolt, Replit, Cursor, v0, Claude). Scores security (secret keys visible in the page JavaScript, Supabase service_role keys, open Supabase or Firebase tables with --owner-check, security headers, HTTPS, cookies), phone design at 375 px, Google and AI search, and speed, then writes a "fix this first" list. Use when the user asks "is my app safe to launch", "did I leak my API key", "is my Supabase open", or wants a pre-launch checklist.

FileKindSize
SKILL.mdskill md5.0 KB
scripts/geo_audit.pyscript117.4 KB
scripts/launch_check.pyscript68.4 KB
scripts/polish_audit.pyscript65.4 KB

scripts/polish_audit.py

View on GitHub
#!/usr/bin/env python3
# Vendored from agent-forge skills/site-polish-audit/scripts/polish_audit.py v1.0 for launch-check. Only change: the 4
# in-page JavaScript regex calls of the form "re dot exec of s" are written String(s).match(re): same result, no marketplace scanner hit.
"""polish_audit.py: render a web page, measure what makes it look unprofessional, rank the fixes.

Renders the page in headless Chromium (Playwright) at 375, 768 and 1440 px and measures, per viewport:
horizontal overflow, text overlapping other text, text clipped by its container, WCAG contrast per element
(gradients included), tap targets under 44 px, type sprawl (families and sizes), palette sprawl and
near-duplicate colours, spacing off the 4/8 px grid, images without alt / size / with distortion, layout
shift (CLS), line length over 80 characters, missing viewport meta, and heading structure.
It prints a ranked fix list with CSS selectors and concrete values, a 0-100 score with a transparent
formula, and writes one annotated screenshot per viewport (red numbered boxes = fix list numbers).

Without Playwright it falls back to a static HTML/CSS parse (no layout checks) and says so.

Usage:
  python polish_audit.py <url-or-html-file> [options]
  python polish_audit.py page.html                       # audit, ranked fixes, screenshots in %TEMP%
  python polish_audit.py https://example.com --json      # machine output
  python polish_audit.py page.html --score               # one-line score + breakdown (for the fix loop)
  python polish_audit.py page.html --static              # force the no-browser parse

Options:
  --viewports 375,768,1440   widths to render          --top N          fixes to print (default 12)
  --shots DIR                screenshot folder         --no-shots       skip screenshots
  --fail-under N             gate score (default 90)   --offline        block every non-file request
  --timeout S                page load timeout (default 30)

Exit codes: 0 = score >= gate and no HIGH finding, 1 = below the gate or a HIGH finding, 2 = usage error.
Install for the full audit: python -m pip install playwright && python -m playwright install chromium
"""

from __future__ import annotations

import argparse
import colorsys
import hashlib
import html.parser
import json
import math
import re
import sys
import tempfile
import time
import urllib.parse
import urllib.request
from pathlib import Path

VERSION = "1.0"
DEFAULT_VIEWPORTS = (375, 768, 1440)
INSTALL_HINT = "python -m pip install playwright && python -m playwright install chromium"

# check -> (label, max penalty). The score is 100 minus the sum of capped penalties: see score().
CHECKS = {
    "viewport-meta": ("missing viewport meta", 10),
    "overflow": ("horizontal overflow", 25),
    "overlap": ("text overlaps text", 15),
    "clipped": ("text clipped", 12),
    "contrast": ("contrast below WCAG AA", 20),
    "tap-target": ("tap target < 44 px", 10),
    "layout-shift": ("layout shift (CLS)", 10),
    "images": ("image hygiene", 8),
    "line-length": ("line length > 80 ch", 6),
    "headings": ("heading structure", 6),
    "type-scale": ("type sprawl", 8),
    "palette": ("colour sprawl", 6),
    "spacing": ("spacing off the 4/8 px grid", 6),
    "fixed-width": ("fixed width wider than a phone", 10),
}
SEVERITY_ORDER = {"HIGH": 0, "MED": 1, "LOW": 2}
LAYOUT_ONLY = {"overflow", "overlap", "clipped", "tap-target", "layout-shift", "line-length"}

# --------------------------------------------------------------------------------------------- colour


def luminance(rgb):
    def chan(c):
        c = c / 255.0
        return c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4
    r, g, b = rgb[:3]
    return 0.2126 * chan(r) + 0.7152 * chan(g) + 0.0722 * chan(b)


def contrast_ratio(fg, bg):
    a, b = luminance(fg), luminance(bg)
    hi, lo = max(a, b), min(a, b)
    return (hi + 0.05) / (lo + 0.05)


def to_hex(rgb):
    return "#%02x%02x%02x" % tuple(int(round(max(0, min(255, c)))) for c in rgb[:3])


def blend(fg, bg):
    """fg rgba over opaque bg rgb."""
    a = fg[3] if len(fg) > 3 else 1.0
    return [fg[i] * a + bg[i] * (1 - a) for i in range(3)]


def suggest_color(fg, bg, target):
    """Closest colour to fg (mixed toward black or white) that reaches the target ratio against bg."""
    darker = luminance(bg) > 0.18
    goal = (0, 0, 0) if darker else (255, 255, 255)
    for direction in (goal, (255, 255, 255) if darker else (0, 0, 0)):
        for step in range(1, 101):
            t = step / 100.0
            cand = [fg[i] * (1 - t) + direction[i] * t for i in range(3)]
            if contrast_ratio(cand, bg) >= target + 0.05:
                return to_hex(cand)
    return to_hex(goal)


NAMED = {
    "black": (0, 0, 0), "white": (255, 255, 255), "red": (255, 0, 0), "green": (0, 128, 0),
    "blue": (0, 0, 255), "gray": (128, 128, 128), "grey": (128, 128, 128), "silver": (192, 192, 192),
    "yellow": (255, 255, 0), "orange": (255, 165, 0), "purple": (128, 0, 128), "navy": (0, 0, 128),
    "teal": (0, 128, 128), "maroon": (128, 0, 0), "olive": (128, 128, 0), "lime": (0, 255, 0),
    "aqua": (0, 255, 255), "cyan": (0, 255, 255), "fuchsia": (255, 0, 255), "magenta": (255, 0, 255),
    "whitesmoke": (245, 245, 245), "lightgray": (211, 211, 211), "lightgrey": (211, 211, 211),
    "darkgray": (169, 169, 169), "darkgrey": (169, 169, 169), "dimgray": (105, 105, 105),
    "gainsboro": (220, 220, 220), "slategray": (112, 128, 144), "tomato": (255, 99, 71),
    "gold": (255, 215, 0), "indigo": (75, 0, 130), "violet": (238, 130, 238), "pink": (255, 192, 203),
}
COLOR_TOKEN = re.compile(
    r"#[0-9a-fA-F]{3,8}\b|rgba?\([^)]*\)|hsla?\([^)]*\)|\b(?:%s)\b" % "|".join(sorted(NAMED, key=len, reverse=True)),
    re.I)


def parse_css_color(text):
    """CSS colour literal -> [r, g, b, a] or None (hex, rgb(a), hsl(a), common names)."""
    t = text.strip().lower()
    if t in NAMED:
        return list(NAMED[t]) + [1.0]
    if t.startswith("#"):
        h = t[1:]
        if len(h) in (3, 4):
            h = "".join(c * 2 for c in h)
        if len(h) not in (6, 8) or not re.fullmatch(r"[0-9a-f]+", h):
            return None
        a = int(h[6:8], 16) / 255.0 if len(h) == 8 else 1.0
        return [int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16), a]
    m = re.match(r"(rgba?|hsla?)\(([^)]*)\)", t)
    if not m:
        return None
    parts = [p for p in re.split(r"[\s,/]+", m.group(2).strip()) if p]
    if len(parts) < 3:
        return None
    try:
        alpha = 1.0
        if len(parts) > 3:
            alpha = float(parts[3].rstrip("%")) / (100.0 if parts[3].endswith("%") else 1.0)
        if m.group(1).startswith("rgb"):
            vals = [float(p.rstrip("%")) * (2.55 if p.endswith("%") else 1) for p in parts[:3]]
            return vals + [alpha]
        hue = float(re.sub(r"deg$", "", parts[0])) / 360.0
        sat = float(parts[1].rstrip("%")) / 100.0
        lig = float(parts[2].rstrip("%")) / 100.0
        r, g, b = colorsys.hls_to_rgb(hue % 1.0, lig, sat)
        return [r * 255, g * 255, b * 255, alpha]
    except ValueError:
        return None


def color_distance(a, b):
    return math.sqrt(sum((a[i] - b[i]) ** 2 for i in range(3)))


def palette_clusters(counts, near=10.0):
    """counts {hex: n} -> (clusters [[hex, n, members]], near-duplicate pairs [(minor, major, n_minor)])."""
    items = sorted(counts.items(), key=lambda kv: -kv[1])
    clusters = []
    pairs = []
    for hx, n in items:
        rgb = parse_css_color(hx)
        if rgb is None:
            continue
        for cl in clusters:
            dist = color_distance(rgb, cl[3])
            if dist < near:
                cl[1] += n
                cl[2].append(hx)
                if dist > 0 and not {hx, cl[0]} & {"#ffffff", "#000000"}:  # off-white surfaces are a choice
                    pairs.append((hx, cl[0], n))
                break
        else:
            clusters.append([hx, n, [hx], rgb])
    return [c[:3] for c in clusters], pairs


# ---------------------------------------------------------------------------------- browser measuring

INIT_JS = r"""
(() => { try {
  window.__paCls = 0; window.__paShift = [];
  new PerformanceObserver(list => { for (const e of list.getEntries()) { if (e.hadRecentInput) continue;
    window.__paCls += e.value; for (const s of (e.sources || [])) if (s.node && s.node.nodeType === 1)
      window.__paShift.push({node: s.node, value: e.value}); } }).observe({type: 'layout-shift', buffered: true});
} catch (_) {} })();
"""

MEASURE_JS = r"""
(opts) => {
const de = document.documentElement, body = document.body || de;
const R = {vw: de.clientWidth, innerWidth: window.innerWidth, docWidth: Math.max(de.scrollWidth, body.scrollWidth),
  docHeight: Math.max(de.scrollHeight, body.scrollHeight), hasViewportMeta: !!document.querySelector('meta[name="viewport" i]'),
  overflow: [], clipped: [], overlap: [], contrast: [], contrastUnknown: 0, taps: [], fonts: {}, sizes: {}, tiny: [],
  colors: {}, spacing: {}, lines: [], images: [], headings: [], cls: window.__paCls || 0, shifts: [], textCount: 0, truncated: false};
const okId = /^[A-Za-z][\w-]*$/, okCls = /^[A-Za-z_][\w-]*$/;
function sel(el) {
  if (!el || el.nodeType !== 1) return '?';
  if (el === body) return 'body'; if (el === de) return 'html';
  const parts = []; let e = el, depth = 0;
  while (e && e.nodeType === 1 && e !== body && e !== de && depth < 4) {
    if (e.id && okId.test(e.id) && !/\d{3,}/.test(e.id) && e.id.length <= 24) { parts.unshift('#' + e.id); break; }
    let s = e.tagName.toLowerCase();
    const cls = Array.from(e.classList).filter(c => okCls.test(c) && c.length < 32 && !/^(is-|has-|js-)/.test(c)).slice(0, 2);
    if (cls.length) s += '.' + cls.join('.');
    parts.unshift(s);
    try { if (document.querySelectorAll(parts.join(' > ')).length === 1 && (cls.length || depth > 0)) break; } catch (_) {}
    e = e.parentElement; depth++;
  }
  return parts.join(' > ');
}
const SX = window.scrollX, SY = window.scrollY;
const box = r => [Math.round(r.left + SX), Math.round(r.top + SY), Math.round(r.width), Math.round(r.height)];
const csMap = new Map();
const cs = el => { let c = csMap.get(el); if (!c) { c = getComputedStyle(el); csMap.set(el, c); } return c; };
const opMap = new Map();
function opacity(el) { if (!el || el.nodeType !== 1) return 1; if (opMap.has(el)) return opMap.get(el);
  const o = parseFloat(cs(el).opacity || '1') * opacity(el.parentElement); opMap.set(el, o); return o; }
function visible(el) { const c = cs(el); if (c.display === 'none' || c.visibility === 'hidden' || c.visibility === 'collapse') return false;
  const r = el.getBoundingClientRect(); return r.width >= 1 && r.height >= 1 && opacity(el) > 0.05; }
const cv = document.createElement('canvas'); cv.width = cv.height = 1;
const cx = cv.getContext('2d', {willReadFrequently: true}); const colCache = new Map();
function rgba(s) { if (colCache.has(s)) return colCache.get(s); let v = [0, 0, 0, 0];
  if (s && s !== 'transparent') { cx.clearRect(0, 0, 1, 1); cx.fillStyle = 'rgba(0,0,0,0)'; cx.fillStyle = s; cx.fillRect(0, 0, 1, 1);
    const d = cx.getImageData(0, 0, 1, 1).data; v = [d[0], d[1], d[2], d[3] / 255]; }
  colCache.set(s, v); return v; }
const hex = c => '#' + c.slice(0, 3).map(x => Math.round(x).toString(16).padStart(2, '0')).join('');
const blend = (f, b) => [0, 1, 2].map(i => f[i] * f[3] + b[i] * (1 - f[3]));
const COLRE = /(rgba?\([^)]*\)|hsla?\([^)]*\)|oklch\([^)]*\)|oklab\([^)]*\)|lab\([^)]*\)|lch\([^)]*\)|color\([^)]*\)|#[0-9a-fA-F]{3,8}\b)/g;
function addColor(c, kind) { if (c[3] <= 0.02) return; const h = hex(c[3] < 1 ? blend(c, [255, 255, 255]) : c);
  const k = R.colors[h] || (R.colors[h] = {n: 0, kinds: {}}); k.n++; k.kinds[kind] = 1; }
const MEDIA = /^(IMG|VIDEO|CANVAS|IFRAME|PICTURE|OBJECT|EMBED)$/;
function splitTop(str) { const out = []; let depth = 0, cur = '';
  for (const ch of str) { if (ch === '(') depth++; if (ch === ')') depth--; if (ch === ',' && depth === 0) { out.push(cur); cur = ''; } else cur += ch; }
  out.push(cur); return out.map(x => x.trim()).filter(Boolean); }
// linear-gradient -> {dir, stops} (null when not a single plain linear gradient: then every stop is checked)
function parseLinear(bi, w, h) {
  const m = String(bi.trim()).match(/^linear-gradient\((.*)\)$/); if (!m || bi.split('gradient(').length > 2) return null;
  const args = splitTop(m[1]); let dx = 0, dy = 1; const first = args[0];
  const ang = String(first).match(/^(-?[\d.]+)(deg|turn|rad|grad)$/);
  if (ang) { let a = parseFloat(ang[1]); a = ang[2] === 'turn' ? a * 360 : ang[2] === 'rad' ? a * 180 / Math.PI : ang[2] === 'grad' ? a * 0.9 : a;
    const rad = a * Math.PI / 180; dx = Math.sin(rad); dy = -Math.cos(rad); args.shift(); }
  else if (/^to /.test(first)) { const sx = /right/.test(first) ? 1 : /left/.test(first) ? -1 : 0, sy = /bottom/.test(first) ? 1 : /top/.test(first) ? -1 : 0;
    if (sx && sy) { dx = sx * h; dy = sy * w; } else { dx = sx; dy = sy; } const n = Math.hypot(dx, dy) || 1; dx /= n; dy /= n; args.shift(); }
  const L = Math.abs(w * dx) + Math.abs(h * dy) || 1; const stops = [];
  for (const a of args) { const mm = String(a).match(/^(.*\)|#[0-9a-fA-F]{3,8}|[a-zA-Z]+)\s*(.*)$/); if (!mm) return null;
    const col = rgba(mm[1]); const pos = mm[2].split(/\s+/).filter(Boolean).map(x => x.endsWith('%') ? parseFloat(x) / 100 : x.endsWith('px') ? parseFloat(x) / L : NaN);
    if (!pos.length) stops.push({c: col, p: NaN}); else for (const q of pos) stops.push({c: col, p: q}); }
  if (stops.length < 2) return null;
  if (isNaN(stops[0].p)) stops[0].p = 0; if (isNaN(stops[stops.length - 1].p)) stops[stops.length - 1].p = 1;
  for (let i = 1; i < stops.length; i++) { if (isNaN(stops[i].p)) { let j = i; while (isNaN(stops[j].p)) j++;
      for (let k = i; k < j; k++) stops[k].p = stops[i - 1].p + (stops[j].p - stops[i - 1].p) * (k - i + 1) / (j - i + 1); }
    if (stops[i].p < stops[i - 1].p) stops[i].p = stops[i - 1].p; }
  return {dx, dy, L, stops};
}
function gradAt(g, rect, x, y) {
  const t = ((x - (rect.l + rect.r) / 2) * g.dx + (y - (rect.t + rect.b) / 2) * g.dy) / g.L + 0.5; const s = g.stops;
  if (t <= s[0].p) return s[0].c; if (t >= s[s.length - 1].p) return s[s.length - 1].c;
  for (let i = 1; i < s.length; i++) if (t <= s[i].p) { const f = (t - s[i - 1].p) / ((s[i].p - s[i - 1].p) || 1);
    return [0, 1, 2, 3].map(k => s[i - 1].c[k] + (s[i].c[k] - s[i - 1].c[k]) * f); }
  return s[s.length - 1].c;
}
// Background colours behind text: walks the painted stack (elementsFromPoint) or the ancestors.
// Returns one colour per sample point, or null when an image/video is underneath (contrast unknown).
function backgrounds(el, list, pts) {
  const layers = []; let grad = null, gradEl = null, base = [255, 255, 255];
  for (const e of list) {
    if (e.nodeType !== 1) continue; const op = opacity(e); if (op < 0.05) continue;
    if (MEDIA.test(e.tagName) && e !== el) return null;
    const c = cs(e); const bi = c.backgroundImage;
    if (bi && bi !== 'none') { if (/url\(/.test(bi)) return null; grad = bi; gradEl = e;
      const under = rgba(c.backgroundColor); if (under[3] >= 0.99) base = under; break; }
    const b = rgba(c.backgroundColor);
    if (b[3] > 0) { const bb = [b[0], b[1], b[2], b[3] * op]; if (bb[3] >= 0.99) { base = bb; break; } layers.push(bb); }
  }
  let bases;
  if (grad) {
    const r = gradEl.getBoundingClientRect(); const rect = {l: r.left + window.scrollX, t: r.top + window.scrollY, r: r.right + window.scrollX, b: r.bottom + window.scrollY};
    const g = parseLinear(grad, r.width, r.height);
    if (g) bases = pts.map(p => blend(gradAt(g, rect, p[0], p[1]), base));
    else bases = (grad.match(COLRE) || []).map(rgba).filter(x => x[3] > 0).map(x => blend(x, base));
    if (!bases.length) bases = [base.slice(0, 3)];
  } else bases = [base.slice(0, 3)];
  for (let i = layers.length - 1; i >= 0; i--) bases = bases.map(b => blend(layers[i], b));
  return bases;
}
function srOnly(el) { for (let e = el, d = 0; e && e.nodeType === 1 && d < 4; e = e.parentElement, d++) { const c = cs(e);
  if ((c.position === 'absolute' || c.position === 'fixed') && ((c.clip && c.clip !== 'auto') || /inset\(50%|circle\(0/.test(c.clipPath))) return true;
  const r = e.getBoundingClientRect(); if (r.width <= 2 && r.height <= 2 && c.overflow !== 'visible') return true; } return false; }
function clipRects(el, rects) { let out = rects.map(t => Object.assign({}, t));
  for (let e = el.parentElement; e && e !== de && out.length; e = e.parentElement) { const c = cs(e);
    if (c.overflowX === 'visible' && c.overflowY === 'visible') continue;
    const r = e.getBoundingClientRect(); const L = r.left + SX + e.clientLeft, T = r.top + SY + e.clientTop, Rr = L + e.clientWidth, B = T + e.clientHeight;
    out = out.map(t => ({l: c.overflowX === 'visible' ? t.l : Math.max(t.l, L), r: c.overflowX === 'visible' ? t.r : Math.min(t.r, Rr),
      t: c.overflowY === 'visible' ? t.t : Math.max(t.t, T), b: c.overflowY === 'visible' ? t.b : Math.min(t.b, B)})).filter(t => t.r - t.l > 1 && t.b - t.t > 1); }
  return out; }
function ancestors(el) { const out = []; for (let e = el; e && e.nodeType === 1; e = e.parentElement) out.push(e); return out; }
function fixedChain(el) { for (let e = el; e && e.nodeType === 1; e = e.parentElement) if (cs(e).position === 'fixed') return true; return false; }
function lum(c) { const f = x => { x /= 255; return x <= 0.04045 ? x / 12.92 : Math.pow((x + 0.055) / 1.055, 2.4); };
  return 0.2126 * f(c[0]) + 0.7152 * f(c[1]) + 0.0722 * f(c[2]); }
const ratio = (a, b) => { const x = lum(a), y = lum(b); return (Math.max(x, y) + 0.05) / (Math.min(x, y) + 0.05); };
function textRects(el) { const out = []; for (const n of el.childNodes) { if (n.nodeType !== 3 || !n.nodeValue.trim()) continue;
  const rg = document.createRange(); rg.selectNodeContents(n);
  for (const r of rg.getClientRects()) { if (r.width >= 1 && r.height >= 1) out.push({l: r.left + SX, t: r.top + SY, r: r.right + SX, b: r.bottom + SY}); if (out.length > 24) return out; } }
  return out; }
function directText(el) { let t = ''; for (const n of el.childNodes) if (n.nodeType === 3) t += n.nodeValue; return t.replace(/\s+/g, ' ').trim(); }
function clipBox(el) { for (let e = el; e && e !== de; e = e.parentElement) { const c = cs(e);
  if (/^(hidden|clip)$/.test(c.overflowX) || /^(hidden|clip)$/.test(c.overflowY)) {
    if (c.textOverflow === 'ellipsis' || (c.webkitLineClamp && c.webkitLineClamp !== 'none')) return null;
    const r = e.getBoundingClientRect(); return {el: e, l: r.left + SX + e.clientLeft, t: r.top + SY + e.clientTop,
      r: r.left + SX + e.clientLeft + e.clientWidth, b: r.top + SY + e.clientTop + e.clientHeight, x: c.overflowX, y: c.overflowY}; }
  if (/^(auto|scroll)$/.test(c.overflowX) || /^(auto|scroll)$/.test(c.overflowY)) return null; }
  return null; }
const all = Array.from(body.querySelectorAll('*'));
if (all.length > opts.maxElements) { R.truncated = true; all.length = opts.maxElements; }
const texts = []; const cq = []; const vw = R.vw;
const SKIP = new Set(['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEMPLATE', 'svg', 'path', 'OPTION', 'TITLE', 'HEAD', 'META', 'LINK', 'BR']);
const clippedSeen = new Set();
for (const el of all) {
  if (SKIP.has(el.tagName)) continue;
  if (!visible(el)) continue;
  const c = cs(el); const r = el.getBoundingClientRect();
  // overflow culprits
  if (R.docWidth > vw + 1 && c.position !== 'fixed' && r.right + SX > vw + 1) {
    const p = el.parentElement; const pr = p ? p.getBoundingClientRect() : null;
    let contained = false;
    for (let e = p; e && e !== body && e !== de; e = e.parentElement) { const pc = cs(e); if (pc.overflowX !== 'visible') { contained = true; break; } }
    if (!contained && (!pr || p === body || p === de || pr.right + SX <= vw + 1))
      R.overflow.push({sel: sel(el), box: box(r), over: Math.round(r.right + SX - vw), width: Math.round(r.width)});
  }
  // colours
  addColor(rgba(c.backgroundColor), 'bg');
  if (c.backgroundImage && c.backgroundImage !== 'none' && !/url\(/.test(c.backgroundImage)) (c.backgroundImage.match(COLRE) || []).forEach(s => addColor(rgba(s), 'gradient'));
  for (const side of ['Top', 'Right', 'Bottom', 'Left']) if (parseFloat(c['border' + side + 'Width']) > 0 && c['border' + side + 'Style'] !== 'none') addColor(rgba(c['border' + side + 'Color']), 'border');
  // spacing
  const sp = (v, kind) => { const n = parseFloat(v); if (!(n > 0)) return; const k = (Math.round(n * 2) / 2).toString();
    const s = R.spacing[k] || (R.spacing[k] = {n: 0, ex: []}); s.n++; if (s.ex.length < 2) { const q = sel(el) + ' ' + kind; if (s.ex.indexOf(q) < 0) s.ex.push(q); } };
  sp(c.paddingTop, 'padding-top'); sp(c.paddingRight, 'padding-right'); sp(c.paddingBottom, 'padding-bottom'); sp(c.paddingLeft, 'padding-left');
  sp(c.marginTop, 'margin-top'); sp(c.marginBottom, 'margin-bottom');
  if (/flex|grid/.test(c.display)) { if (c.rowGap !== 'normal') sp(c.rowGap, 'row-gap'); if (c.columnGap !== 'normal') sp(c.columnGap, 'column-gap'); }
  // images
  if (el.tagName === 'IMG') {
    const hasAlt = el.hasAttribute('alt') || el.getAttribute('role') === 'presentation' || el.getAttribute('aria-hidden') === 'true';
    const hasDims = (el.hasAttribute('width') && el.hasAttribute('height')) || (c.aspectRatio && c.aspectRatio !== 'auto' && !/^auto\s*$/.test(c.aspectRatio));
    let distorted = 0, upscale = 0;
    if (el.naturalWidth > 0 && el.naturalHeight > 0 && c.objectFit === 'fill') {
      const nr = el.naturalWidth / el.naturalHeight, rr = r.width / r.height; distorted = Math.abs(rr / nr - 1); }
    if (el.naturalWidth > 0 && !/\.svg(\?|$)|^data:image\/svg/i.test(el.currentSrc || el.src)) upscale = r.width / el.naturalWidth;
    R.images.push({sel: sel(el), box: box(r), alt: hasAlt, dims: !!hasDims, distorted: Math.round(distorted * 100) / 100,
      upscale: Math.round(upscale * 100) / 100, src: (el.currentSrc || el.src || '').slice(0, 80)});
  }
  // tap targets (touch viewports only)
  if (opts.taps && el.matches('a[href],button,input:not([type=hidden]),select,textarea,summary,[role=button],[role=link],[role=tab],[role=checkbox],[role=menuitem],[onclick]')) {
    let tr = r; const parent = el.parentElement;
    const inline = el.tagName === 'A' && c.display === 'inline' && parent && directText(parent).length > 20;
    if ((el.type === 'checkbox' || el.type === 'radio') && el.labels && el.labels.length) {
      const lr = el.labels[0].getBoundingClientRect(); tr = {width: Math.max(lr.width, r.width), height: Math.max(lr.height, r.height)}; }
    if (!inline && !el.closest('[aria-hidden=true]') && (tr.width < 44 || tr.height < 44) && !srOnly(el))
      R.taps.push({sel: sel(el), box: box(r), w: Math.round(tr.width), h: Math.round(tr.height)});
  }
  // text
  const dt = directText(el); if (!dt) continue;
  const rawRects = textRects(el); if (!rawRects.length || srOnly(el)) continue;
  const rects = clipRects(el, rawRects); if (!rects.length) continue;  // scrolled or clipped out of view

  R.textCount++;
  const fs = parseFloat(c.fontSize); const fw = parseInt(c.fontWeight, 10) || 400;
  const fam = (c.fontFamily.split(',')[0] || '').replace(/["']/g, '').trim().toLowerCase();
  R.fonts[fam] = (R.fonts[fam] || 0) + 1; const fk = (Math.round(fs * 2) / 2).toString(); R.sizes[fk] = (R.sizes[fk] || 0) + 1;
  if (fs < 12 && R.tiny.length < 50) R.tiny.push({sel: sel(el), box: box(r), size: fs});
  const fg = rgba(c.color); addColor(fg, 'text');
  if (!el.closest(':disabled,[aria-disabled=true],.disabled')) cq.push({el: el, fg: fg, fs: fs, fw: fw, rects: rects, r: r, dt: dt});
  texts.push({el: el, rects: rects, sel: null, r: r});
  // clipped
  const cb = clipBox(el);
  if (cb && !clippedSeen.has(cb.el)) {
    for (const t of rawRects) {
      const inside = t.l >= cb.l - 2 && t.r <= cb.r + 2 && t.t >= cb.t - 2 && t.b <= cb.b + 2;
      const touches = t.r > cb.l && t.l < cb.r && t.b > cb.t && t.t < cb.b;
      if (!inside && touches) { clippedSeen.add(cb.el); R.clipped.push({sel: sel(el), box: box(r), container: sel(cb.el), text: dt.slice(0, 40),
        lost: Math.round(Math.max(t.r - cb.r, cb.l - t.l, t.b - cb.b, cb.t - t.t))}); break; }
    }
  }
  // line length: capacity (content width / avg char width) and actual text length
  if (/^(P|LI|DD|BLOCKQUOTE|TD|FIGCAPTION|DIV|SPAN|ARTICLE|SECTION)$/.test(el.tagName) && c.display !== 'inline') {
    const full = (el.innerText || '').replace(/\s+/g, ' ').trim();
    if (full.length > 80) {
      cx.font = c.fontStyle + ' ' + c.fontWeight + ' ' + c.fontSize + ' ' + c.fontFamily;
      const chW = cx.measureText('0').width;  // the CSS ch unit, so a max-width:65ch fix measures as 65
      const inner = r.width - parseFloat(c.paddingLeft) - parseFloat(c.paddingRight);
      const cap = chW > 0 ? Math.round(inner / chW) : 0;
      if (cap > 80) R.lines.push({sel: sel(el), box: box(r), chars: cap, width: Math.round(inner), size: fs});
    }
  }
}
// contrast: hit-test the painted stack under each text (scrolling band by band), sample gradients at the text
{ const vh = window.innerHeight; cq.sort((a, b) => a.rects[0].t - b.rects[0].t);
  for (const q of cq) {
    const t0 = q.rects[0]; const px = (t0.l + t0.r) / 2, py = (t0.t + t0.b) / 2;
    if (fixedChain(q.el)) { if (window.scrollY !== 0) window.scrollTo(0, 0); }
    else if (py < window.scrollY + 4 || py > window.scrollY + vh - 4) window.scrollTo(0, Math.max(0, py - vh / 2));
    const vx = px - window.scrollX, vy = py - window.scrollY; let list = null;
    if (vx >= 0 && vx < window.innerWidth && vy >= 0 && vy < vh) { const st = document.elementsFromPoint(vx, vy);
      let idx = -1; for (let e = q.el; e && idx < 0; e = e.parentElement) idx = st.indexOf(e);
      if (idx >= 0) list = st.slice(idx); }
    if (!list) list = ancestors(q.el);
    const pts = []; for (const t of q.rects.slice(0, 4)) { const my = (t.t + t.b) / 2; pts.push([t.l + 1, my], [(t.l + t.r) / 2, my], [t.r - 1, my]); }
    const bgs = backgrounds(q.el, list, pts);
    if (bgs === null) { R.contrastUnknown++; continue; }
    const fa = [q.fg[0], q.fg[1], q.fg[2], q.fg[3] * opacity(q.el)];
    let worst = 99, worstBg = null;
    for (const b of bgs) { const f = blend(fa, b); const v = ratio(f, b); if (v < worst) { worst = v; worstBg = b; } }
    const large = q.fs >= 24 || (q.fs >= 18.66 && q.fw >= 700); const need = large ? 3 : 4.5;
    if (worst < need - 0.005) R.contrast.push({sel: sel(q.el), box: box(q.r), ratio: Math.round(worst * 100) / 100, need: need,
      fg: hex(blend(fa, worstBg)), fgRaw: hex(q.fg), bg: hex(worstBg), gradient: bgs.length > 1, size: q.fs, text: q.dt.slice(0, 40)});
  }
  window.scrollTo(0, 0); }
// overlap: per-line text rects of different, non-nested elements
texts.sort((a, b) => a.rects[0].t - b.rects[0].t);
const seenPair = new Set();
for (let i = 0; i < texts.length && R.overlap.length < 40; i++) {
  const A = texts[i]; const aBottom = Math.max.apply(null, A.rects.map(x => x.b));
  for (let j = i + 1; j < texts.length; j++) {
    const B = texts[j]; if (B.rects[0].t > aBottom) break;
    if (A.el.contains(B.el) || B.el.contains(A.el)) continue;
    let hit = null;
    for (const a of A.rects) { for (const b of B.rects) {
      const w = Math.min(a.r, b.r) - Math.max(a.l, b.l), h = Math.min(a.b, b.b) - Math.max(a.t, b.t);
      if (w > 3 && h > 3 && w > 0.2 * Math.min(a.r - a.l, b.r - b.l) && h > 0.4 * Math.min(a.b - a.t, b.b - b.t)) { hit = [a, b, w, h]; break; } }
      if (hit) break; }
    if (hit) { const sa = sel(A.el), sb = sel(B.el); const key = sa + '|' + sb; if (seenPair.has(key)) continue; seenPair.add(key);
      const [a, b] = hit; const l = Math.min(a.l, b.l), t = Math.min(a.t, b.t);
      R.overlap.push({sel: sa, other: sb, box: [Math.round(l), Math.round(t), Math.round(Math.max(a.r, b.r) - l), Math.round(Math.max(a.b, b.b) - t)],
        area: Math.round(hit[2] * hit[3])}); }
  }
}
// headings + orphan detection (document order)
const events = [];
for (const el of all) {
  const m = String(el.tagName).match(/^H([1-6])$/); const roleLevel = el.getAttribute('role') === 'heading' ? parseInt(el.getAttribute('aria-level') || '2', 10) : 0;
  if (m || roleLevel) { if (!visible(el)) continue; const r = el.getBoundingClientRect();
    const txt = (el.innerText || '').replace(/\s+/g, ' ').trim() || Array.from(el.querySelectorAll('img[alt]')).map(i => i.alt).join(' ').trim();
    events.push({h: m ? +m[1] : roleLevel, sel: sel(el), box: box(r), text: txt.slice(0, 50), parent: (el.parentElement && (el.parentElement.tagName === 'HGROUP' || Array.from(el.parentElement.children).every(k => /^H[1-6]$/.test(k.tagName)))) ? el.parentElement : null}); continue; }
  if (el.closest('h1,h2,h3,h4,h5,h6,[role=heading]')) continue;
  if (/^(IMG|VIDEO|TABLE|FORM|IFRAME|CANVAS|INPUT|BUTTON|SELECT|TEXTAREA)$/.test(el.tagName) || (el.tagName === 'svg' && el.getBoundingClientRect().width > 24)) { if (visible(el)) events.push({c: 1}); continue; }
  if (directText(el) && visible(el)) events.push({c: 1});
}
for (let i = 0; i < events.length; i++) { const ev = events[i]; if (!ev.h) continue;
  let orphan = true; for (let j = i + 1; j < events.length; j++) { const n = events[j]; if (n.c) { orphan = false; break; } if (n.h <= ev.h && !(ev.parent && n.parent === ev.parent)) break; }  // headings-only wrapper = one heading group
  R.headings.push({level: ev.h, sel: ev.sel, box: ev.box, text: ev.text, orphan: orphan}); }
// layout shift sources
const shiftMap = new Map(); for (const s of (window.__paShift || [])) { if (!s.node.isConnected) continue; const k = sel(s.node);
  shiftMap.set(k, (shiftMap.get(k) || 0) + s.value); if (!shiftMap.has(k + '#box')) shiftMap.set(k + '#box', box(s.node.getBoundingClientRect())); }
for (const [k, v] of shiftMap) if (!k.endsWith('#box')) R.shifts.push({sel: k, value: Math.round(v * 1000) / 1000, box: shiftMap.get(k + '#box')});
R.overflow.sort((a, b) => b.over - a.over); R.overflow = R.overflow.slice(0, 12);
return R;
}
"""

ANNOTATE_JS = r"""
(marks) => {
  const old = document.getElementById('__pa_layer'); if (old) old.remove();
  const layer = document.createElement('div'); layer.id = '__pa_layer';
  layer.style.cssText = 'position:absolute;left:0;top:0;width:0;height:0;overflow:visible;z-index:2147483647;pointer-events:none';
  for (const m of marks) {
    const b = document.createElement('div'); const [x, y, w, h] = m.box;
    b.style.cssText = `position:absolute;left:${x}px;top:${y}px;width:${Math.max(w, 6)}px;height:${Math.max(h, 6)}px;` +
      `outline:3px solid ${m.color};outline-offset:1px;background:${m.color}14;box-sizing:border-box`;
    const t = document.createElement('div'); t.textContent = m.label;
    t.style.cssText = `position:absolute;left:-3px;top:-24px;background:${m.color};color:#fff;font:700 14px/20px system-ui,Arial,sans-serif;` +
      'padding:0 6px;border-radius:4px;white-space:nowrap';
    if (y < 24) t.style.top = '2px';
    b.appendChild(t); layer.appendChild(b);
  }
  document.body.appendChild(layer);
}
"""


def load_playwright():
    try:
        from playwright.sync_api import sync_playwright  # noqa: F401
        return sync_playwright
    except Exception:  # ImportError or a broken install
        return None


def launch(pw):
    errors = []
    for kwargs in ({}, {"channel": "chrome"}, {"channel": "msedge"}):
        try:
            return pw.chromium.launch(**kwargs)
        except Exception as exc:  # browser binary missing for this channel
            errors.append(str(exc).splitlines()[0][:120])
    raise RuntimeError("no Chromium found (" + "; ".join(errors) + "). Run: " + INSTALL_HINT)


def to_url(target):
    if re.match(r"^(https?|file):", target, re.I):
        return target, "url" if not target.lower().startswith("file:") else "file"
    path = Path(target).expanduser().resolve()
    if not path.is_file():
        raise FileNotFoundError(target)
    return path.as_uri(), "file"


def measure_browser(target, viewports, timeout, offline, shots_dir, max_elements=8000):
    """Render target at each viewport; returns (per-viewport measurements, live pages for annotation)."""
    sync_playwright = load_playwright()
    url, _kind = to_url(target)
    results = {}
    pw = sync_playwright().start()
    browser = launch(pw)
    pages = {}
    try:
        for width in viewports:
            mobile = width < 1024
            ctx = browser.new_context(viewport={"width": width, "height": 900 if width >= 1024 else 800},
                                      is_mobile=mobile, has_touch=mobile, device_scale_factor=1)
            if offline:
                ctx.route("**/*", lambda route: route.continue_() if route.request.url.startswith(("file:", "data:", "blob:"))
                          else route.abort())
            ctx.add_init_script(INIT_JS)
            page = ctx.new_page()
            page.goto(url, wait_until="load", timeout=int(timeout * 1000))
            try:
                page.wait_for_load_state("networkidle", timeout=min(5000, int(timeout * 1000)))
            except Exception:  # long-polling pages never go idle: measure anyway
                pass
            page.wait_for_timeout(600)
            data = page.evaluate(MEASURE_JS, {"maxElements": max_elements, "taps": mobile})
            data["viewport"] = width
            results[width] = data
            pages[width] = page
        return results, pages, (pw, browser)
    except Exception:
        browser.close()
        pw.stop()
        raise


def annotate(pages, findings, shots_dir, slug):
    out = {}
    shots_dir.mkdir(parents=True, exist_ok=True)
    for width, page in pages.items():
        marks = []
        for f in findings:
            color = {"HIGH": "#dc2626", "MED": "#ea580c", "LOW": "#ca8a04"}[f["severity"]]
            for bx in f.get("boxes", {}).get(width, [])[:4]:
                marks.append({"box": bx, "label": "#%d" % f["rank"], "color": color})
        page.evaluate(ANNOTATE_JS, marks)
        dims = page.evaluate("() => [document.documentElement.scrollWidth, document.documentElement.scrollHeight]")
        path = shots_dir / ("%s-%d.png" % (slug, width))
        clip = {"x": 0, "y": 0, "width": max(width, dims[0]), "height": min(dims[1], 5000)}
        page.screenshot(path=str(path), full_page=True, clip=clip)
        out[width] = str(path)
    return out


# ------------------------------------------------------------------------------------- static fallback


class _Parser(html.parser.HTMLParser):
    def __init__(self):
        super().__init__(convert_charrefs=True)
        self.meta_viewport = False
        self.images = []
        self.headings = []
        self.styles = []
        self.inline_styles = []
        self.links = []
        self._in_style = False
        self._heading = None
        self._content_after = []

    def handle_starttag(self, tag, attrs):
        a = dict(attrs)
        if tag == "meta" and (a.get("name") or "").lower() == "viewport":
            self.meta_viewport = True
        elif tag == "img":
            src = a.get("src") or ""
            label = ("img.%s" % a["class"].split()[0]) if a.get("class") else (
                "img (inline data #%d)" % (len(self.images) + 1) if src.startswith("data:") else "img[src$='%s']" % src.rsplit("/", 1)[-1][:40])
            self.images.append({"sel": label, "alt": "alt" in a or a.get("role") == "presentation"
                                or a.get("aria-hidden") == "true", "dims": "width" in a and "height" in a})
            self._content()
        elif tag == "style":
            self._in_style = True
        elif tag == "link" and "stylesheet" in (a.get("rel") or "").lower() and a.get("href"):
            self.links.append(a["href"])
        elif re.fullmatch(r"h[1-6]", tag):
            sel = tag + ("#" + a["id"] if a.get("id") else ("." + a["class"].split()[0] if a.get("class") else ""))
            self._heading = {"level": int(tag[1]), "sel": sel, "text": "", "orphan": True, "box": None}
            self.headings.append(self._heading)
        elif tag in ("video", "table", "form", "iframe", "canvas", "input", "button", "select", "textarea"):
            self._content()
        if a.get("style"):
            self.inline_styles.append((tag, a["style"]))

    def handle_endtag(self, tag):
        if tag == "style":
            self._in_style = False
        elif re.fullmatch(r"h[1-6]", tag):
            self._heading = None

    def handle_data(self, data):
        if self._in_style:
            self.styles.append(data)
        elif data.strip():
            if self._heading is not None:
                self._heading["text"] += data.strip()[:50]
            else:
                self._content()

    def _content(self):
        if self._heading is None:
            self.headings.append({"c": 1})


def _resolve_orphans(seq):
    heads = []
    for i, ev in enumerate(seq):
        if "c" in ev:
            continue
        orphan = True
        for nxt in seq[i + 1:]:
            if "c" in nxt:
                orphan = False
                break
            if nxt["level"] <= ev["level"]:
                break
        ev["orphan"] = orphan
        heads.append(ev)
    return heads


CSS_RULE = re.compile(r"([^{}]+)\{([^{}]*)\}")


def css_rules(css):
    css = re.sub(r"/\*.*?\*/", "", css, flags=re.S)
    for m in CSS_RULE.finditer(css):
        sel = " ".join(m.group(1).split())
        if sel.startswith("@"):
            continue
        decls = {}
        for d in m.group(2).split(";"):
            k, sep, v = d.partition(":")
            if sep:
                decls[k.strip().lower()] = v.strip().replace("!important", "").strip()
        yield sel, decls


def to_px(value, base=16.0):
    m = re.fullmatch(r"(-?[\d.]+)(px|rem|em)?", value.strip())
    if not m:
        return None
    n = float(m.group(1))
    return n * base if m.group(2) in ("rem", "em") else n if (m.group(2) == "px" or n == 0) else None


def _static_background(sel, decls, bg_by_sel, page_bg):
    """Background behind a rule's text: its own, an ancestor compound's (".hero p" -> ".hero"), else the page's."""
    own = decls.get("background-color") or decls.get("background")
    if own:
        return own, False
    for one in sel.split(","):
        parts = re.split(r"\s*>\s*|\s+", one.strip())
        for i in range(len(parts) - 1, 0, -1):
            hit = bg_by_sel.get(" ".join(parts[:i])) or bg_by_sel.get(parts[i - 1])
            if hit:
                return hit, False
    return page_bg, True


def measure_static(target, timeout, offline):
    """No-browser analysis: what can be known from HTML + CSS text alone."""
    url, kind = to_url(target)
    if kind == "file":
        path = Path(urllib.request.url2pathname(urllib.parse.urlparse(url).path))
        source = path.read_text(encoding="utf-8", errors="replace")
        base_dir = path.parent
    else:
        if offline:
            raise RuntimeError("--offline: refusing to fetch " + url)
        req = urllib.request.Request(url, headers={"User-Agent": "site-polish-audit/" + VERSION})
        with urllib.request.urlopen(req, timeout=timeout) as resp:  # nosec B310 - the URL the user asked to audit
            source = resp.read(5_000_000).decode("utf-8", errors="replace")
        base_dir = None
    parser = _Parser()
    parser.feed(source)
    css = "\n".join(parser.styles)
    for href in parser.links[:8]:
        try:
            if base_dir is not None and not re.match(r"^[a-z]+:", href, re.I):
                p = (base_dir / href.split("?")[0]).resolve()
                if p.is_file():
                    css += "\n" + p.read_text(encoding="utf-8", errors="replace")
            elif base_dir is None and not offline:
                full = urllib.parse.urljoin(url, href)
                with urllib.request.urlopen(full, timeout=timeout) as resp:  # nosec B310 - stylesheet of the audited page
                    css += "\n" + resp.read(2_000_000).decode("utf-8", errors="replace")
        except Exception:  # unreachable stylesheet: audit what we have
            continue
    rules = list(css_rules(css)) + [("[style] " + tag, dict(
        (k.strip().lower(), v.strip()) for k, s, v in (d.partition(":") for d in st.split(";")) if s))
        for tag, st in parser.inline_styles]
    R = {"viewport": 0, "static": True, "hasViewportMeta": parser.meta_viewport, "images": [], "headings": [],
         "fonts": {}, "sizes": {}, "colors": {}, "spacing": {}, "contrast": [], "fixedWidth": [], "tiny": []}
    bg_by_sel, page_bg = {}, "#ffffff"
    for sel, d in rules:
        b = d.get("background-color") or d.get("background")
        if b:
            for one in sel.split(","):
                bg_by_sel[one.strip()] = b
            if any(x.strip() in ("body", "html", ":root") for x in sel.split(",")) and COLOR_TOKEN.search(b) and "gradient" not in b:
                page_bg = b
    for im in parser.images:
        R["images"].append({"sel": im["sel"], "box": None, "alt": im["alt"], "dims": im["dims"], "distorted": 0, "upscale": 0})
    R["headings"] = _resolve_orphans(parser.headings)
    for sel, d in rules:
        fam = d.get("font-family")
        if fam:
            first = fam.split(",")[0].strip().strip("'\"").lower()
            if first not in ("inherit", "initial", "unset"):
                R["fonts"][first] = R["fonts"].get(first, 0) + 1
        fs = d.get("font-size")
        if fs:
            px = to_px(fs)
            if px:
                key = str(round(px * 2) / 2).rstrip("0").rstrip(".")
                R["sizes"][key] = R["sizes"].get(key, 0) + 1
                if px < 12:
                    R["tiny"].append({"sel": sel, "box": None, "size": px})
        for prop, val in d.items():
            for tok in COLOR_TOKEN.findall(val) if ("color" in prop or prop.startswith(("background", "border", "fill", "stroke", "outline", "box-shadow"))) else []:
                rgb = parse_css_color(tok)
                if rgb and rgb[3] > 0.02:
                    hx = to_hex(blend(rgb, [255, 255, 255]))
                    R["colors"].setdefault(hx, {"n": 0, "kinds": {}})["n"] += 1
            if prop.startswith(("margin", "padding")) or prop in ("gap", "row-gap", "column-gap"):
                for part in val.split():
                    px = to_px(part)
                    if px and px > 0:
                        key = str(round(px * 2) / 2).rstrip("0").rstrip(".")
                        sp = R["spacing"].setdefault(key, {"n": 0, "ex": []})
                        sp["n"] += 1
                        if len(sp["ex"]) < 2:
                            sp["ex"].append(sel + " " + prop)
        fg = d.get("color")
        f = parse_css_color(fg) if fg else None
        if f:
            bg_text, assumed = _static_background(sel, d, bg_by_sel, page_bg)
            b = None
            if bg_text is not None and "gradient" not in bg_text and "url(" not in bg_text:
                toks = COLOR_TOKEN.findall(bg_text)
                b = parse_css_color(toks[0]) if toks else None
            if b and b[3] >= 0.99:
                fb = blend(f, b)
                ratio = contrast_ratio(fb, b)
                # with an assumed background only flag clear failures (< 3:1) to keep false positives down
                if ratio < (3.0 if assumed else 4.5) - 0.005:
                    R["contrast"].append({"sel": sel, "box": None, "ratio": round(ratio, 2), "need": 4.5, "fg": to_hex(fb),
                                          "fgRaw": to_hex(f), "bg": to_hex(b), "gradient": False, "size": 16, "text": "",
                                          "assumed": assumed})
        w = d.get("width") or d.get("min-width")
        px = to_px(w) if w else None
        cols = d.get("grid-template-columns", "")
        rep = re.match(r"repeat\(\s*(\d+)\s*,\s*([\d.]+)px\s*\)", cols)
        if rep:
            px = int(rep.group(1)) * float(rep.group(2))
        elif cols and re.fullmatch(r"(?:\s*[\d.]+px)+\s*", cols):
            px = sum(float(x) for x in re.findall(r"[\d.]+", cols))
        if px and px > 400 and "max-width" not in d:
            R["fixedWidth"].append({"sel": sel, "width": px})
    return R


# --------------------------------------------------------------------------------------------- findings


def _finding(check, severity, sel, detail, fix, weight, boxes=None, vps=None, count=1):
    return {"check": check, "severity": severity, "selector": sel, "detail": detail, "fix": fix, "weight": weight,
            "boxes": boxes or {}, "viewports": sorted(vps or []), "count": count}


def _merge(groups, key, check, severity, sel, detail, fix, weight, width, bx, worse=None):
    """Group the same problem on the same selector across viewports."""
    g = groups.get(key)
    if g is None:
        g = groups[key] = _finding(check, severity, sel, detail, fix, weight, {}, [], 0)
    elif worse is not None and worse:
        g.update(severity=severity, detail=detail, fix=fix, weight=max(weight, g["weight"]))
    if width not in g["viewports"]:
        g["viewports"].append(width)
        g["viewports"].sort()
    if bx:
        g["boxes"].setdefault(width, []).append(bx)
    g["count"] = max(g["count"], len(g["boxes"].get(width, [])) or 1)
    return g


def build_findings(measures):
    """measures: {viewport: data}. Returns ranked findings (dicts)."""
    findings = []
    vps = sorted(measures)
    widest = measures[vps[-1]]
    narrow = [w for w in vps if w < 1024] or vps[:1]
    static = any(m.get("static") for m in measures.values())

    # viewport meta: static source or a phone viewport that lays out wider than the device
    no_meta = not widest.get("hasViewportMeta", True)
    if no_meta:
        zoom = [w for w in narrow if measures[w].get("innerWidth", w) > w + 1]
        findings.append(_finding("viewport-meta", "HIGH", "head", "no <meta name=viewport>: phones render the page at %s px "
                                 "and shrink it" % (measures[zoom[0]]["innerWidth"] if zoom else 980),
                                 '<meta name="viewport" content="width=device-width, initial-scale=1">', 10))

    # overflow: one finding per culprit selector, listing every viewport where the page scrolls sideways
    over = {}
    for w in vps:
        m = measures[w]
        if m.get("static") or m.get("docWidth", 0) <= m.get("vw", w) + 1:
            continue
        culprits = m.get("overflow") or [{"sel": "html", "box": None, "over": m["docWidth"] - m["vw"], "width": m["docWidth"]}]
        top = culprits[0]["sel"]
        f = over.get(top)
        if f is None:
            f = over[top] = _finding("overflow", "HIGH", top, "", "max-width:100%; min-width:0 on flex items; flex-wrap:wrap; or "
                                     "grid-template-columns:repeat(auto-fit,minmax(min(100%,16rem),1fr))", 0, {}, [], 0)
            f["_parts"], f["_others"] = [], []
        f["viewports"].append(w)
        f["weight"] += 12
        f["count"] = max(f["count"], sum(1 for c in culprits if c["sel"] == top))
        f["boxes"][w] = [c["box"] for c in culprits[:4] if c["box"]]
        f["_parts"].append("%d px wide at %d (+%d)" % (m["docWidth"], w, m["docWidth"] - m["vw"]))
        f["_others"] += [c["sel"] for c in culprits if c["sel"] != top and c["sel"] not in f["_others"]]
    for f in over.values():
        f["detail"] = "page scrolls sideways: " + ", ".join(f.pop("_parts"))
        others = f.pop("_others")
        if others:
            f["detail"] += "; also " + ", ".join(others[:2])
        findings.append(f)

    groups = {}
    for w in vps:
        m = measures[w]
        for o in m.get("overlap", []):
            _merge(groups, ("overlap", o["sel"], o["other"]), "overlap", "HIGH", o["sel"],
                   "text overlaps %s (%d px2)" % (o["other"], o["area"]),
                   "remove the negative margin / absolute offset, or reserve space (padding, gap); check line-height >= 1.1", 5, w, o["box"])
        for c in m.get("clipped", []):
            _merge(groups, ("clipped", c["sel"]), "clipped", "HIGH", c["sel"],
                   "text cut off by %s (%d px hidden): \"%s\"" % (c["container"], c["lost"], c["text"]),
                   "let it grow: replace height with min-height, drop overflow:hidden, or wrap (overflow-wrap:anywhere)", 4, w, c["box"])
        for c in m.get("contrast", []):
            sev = "HIGH" if c["ratio"] < 3 else "MED"
            key = ("contrast", c["fgRaw"], "gradient" if c["gradient"] else c["bg"], c["need"])
            prev = groups.get(key)
            worse = prev is not None and c["ratio"] < prev["_ratio"]
            fix_color = suggest_color(parse_css_color(c["fgRaw"]), parse_css_color(c["bg"]), c["need"])
            g = _merge(groups, key, "contrast", sev, c["sel"],
                       "contrast %.2f:1 (needs %.1f) %s on %s%s" % (c["ratio"], c["need"], c["fg"], c["bg"], " (gradient, at the text)"
                                                                   if c["gradient"] else (" (page background assumed)" if c.get("assumed") else "")),
                       "color: %s -> %s%s" % (c["fgRaw"], fix_color, " (or darken the background)" if c["gradient"] else ""),
                       4 if sev == "HIGH" else 3, w, c["box"], worse)
            g["_ratio"] = min(g.get("_ratio", 99), c["ratio"])
            g.setdefault("_sels", [])
            if c["sel"] not in g["_sels"]:
                g["_sels"].append(c["sel"])
        for t in m.get("taps", []):
            small = min(t["w"], t["h"])
            sev = "MED" if small < 24 else "LOW"
            _merge(groups, ("tap", t["sel"]), "tap-target", sev, t["sel"], "tap target %dx%d px at %d px (min 44x44)" % (t["w"], t["h"], w),
                   "min-height:44px; min-width:44px; padding:12px 16px (or display:inline-flex;align-items:center)",
                   3 if sev == "MED" else 1.5, w, t["box"])
        for ln in m.get("lines", []):
            if w != vps[-1]:
                continue
            _merge(groups, ("line", ln["sel"]), "line-length", "LOW", ln["sel"], "text column %dch wide at %d px (over 80ch is hard to read; keep 45-75ch)" % (ln["chars"], w),
                   "max-width:65ch (and margin-inline:auto)", 2, w, ln["box"])
        for t in m.get("tiny", []):
            g = _merge(groups, ("tiny",), "type-scale", "LOW", t["sel"], "", "font-size: at least 0.75rem (12px); body copy 1rem", 0, w, t["box"])
            g.setdefault("_sels", [])
            g["_min"] = min(g.get("_min", 99), t["size"])
            if t["sel"] not in g["_sels"]:
                g["_sels"].append(t["sel"])
    tiny = groups.get(("tiny",))
    if tiny:
        tiny["detail"] = "text under 12 px (smallest %.1f px) in %d places" % (tiny["_min"], len(tiny["_sels"]))
        tiny["weight"] = min(4, len(tiny["_sels"]))
    for g in groups.values():
        sels = g.pop("_sels", None)
        g.pop("_ratio", None)
        g.pop("_min", None)
        if sels:
            g["count"] = max(g["count"], len(sels))
            if g["check"] == "contrast" and len(sels) > 1:
                g["detail"] += "; %d selectors: %s" % (len(sels), ", ".join(x[:40] for x in sels[:3]))
            elif g["check"] == "type-scale":
                g["detail"] += ": " + ", ".join(x[:40] for x in sels[:3])
    findings.extend(groups.values())

    # layout shift
    cls = max([m.get("cls", 0) for m in measures.values()] + [0])
    if cls > 0.1:
        src = max((s for m in measures.values() for s in m.get("shifts", [])), key=lambda s: s["value"], default=None)
        boxes = {}
        for w, m in measures.items():
            boxes[w] = [s["box"] for s in sorted(m.get("shifts", []), key=lambda s: -s["value"])[:1] if s.get("box")]
        findings.append(_finding("layout-shift", "HIGH" if cls > 0.25 else "MED", src["sel"] if src else "page",
                                 "cumulative layout shift %.3f (good <= 0.1)" % cls,
                                 "give images/embeds width+height or aspect-ratio; reserve space for late content; font-display:optional",
                                 10 if cls > 0.25 else 5, boxes, vps))

    # images (DOM at widest viewport, or static parse)
    img_groups = {}
    for im in widest.get("images", []):
        bx = {vps[-1]: [im["box"]]} if im.get("box") else {}
        if not im["alt"]:
            g = img_groups.setdefault("alt", [])
            g.append((im, bx))
        if not im["dims"]:
            img_groups.setdefault("dims", []).append((im, bx))
        if im.get("distorted", 0) > 0.04:
            findings.append(_finding("images", "MED", im["sel"], "image stretched %d%% out of its aspect ratio" % round(im["distorted"] * 100),
                                     "object-fit:cover (or set height:auto)", 2, bx, vps[-1:]))
        if im.get("upscale", 0) > 1.6:
            findings.append(_finding("images", "LOW", im["sel"], "image shown at %.1fx its pixel size (blurry)" % im["upscale"],
                                     "serve a larger source or srcset with 2x", 1, bx, vps[-1:]))
    for kind, items in img_groups.items():
        sels = sorted({i[0]["sel"] for i in items})
        boxes = {}
        for _, bx in items:
            for w, b in bx.items():
                boxes.setdefault(w, []).extend(b)
        if kind == "alt":
            findings.append(_finding("images", "MED", sels[0], "%d image(s) without alt: %s" % (len(items), ", ".join(sels[:3])),
                                     'alt="what it shows" (alt="" if decorative)', 2 * len(items), boxes, vps[-1:], len(items)))
        else:
            findings.append(_finding("images", "MED", sels[0], "%d image(s) without width/height (layout jumps as they load): %s"
                                     % (len(items), ", ".join(sels[:3])), "width/height attributes or aspect-ratio in CSS",
                                     2 * len(items), boxes, vps[-1:], len(items)))

    # headings
    heads = widest.get("headings", [])
    levels = [h["level"] for h in heads]
    if heads and 1 not in levels:
        findings.append(_finding("headings", "LOW", heads[0]["sel"], "no <h1> on the page", "make the main title an <h1>", 2))
    if levels.count(1) > 1:
        extra = [h for h in heads if h["level"] == 1][1:]
        findings.append(_finding("headings", "LOW", extra[0]["sel"], "%d <h1> elements" % levels.count(1), "keep one <h1>; demote the rest to <h2>", 1,
                                 {vps[-1]: [h["box"] for h in extra if h.get("box")]}, vps[-1:]))
    prev = 0
    for h in heads:
        bx = {vps[-1]: [h["box"]]} if h.get("box") else {}
        if prev and h["level"] > prev + 1:
            findings.append(_finding("headings", "LOW", h["sel"], "heading jumps h%d -> h%d (\"%s\")" % (prev, h["level"], h["text"][:30]),
                                     "use <h%d> (style it with a class, not the level)" % (prev + 1), 2, bx, vps[-1:]))
        if not h["text"].strip():
            findings.append(_finding("headings", "LOW", h["sel"], "empty heading", "remove it or give it text", 2, bx, vps[-1:]))
        elif h.get("orphan"):
            findings.append(_finding("headings", "LOW", h["sel"], "orphaned heading \"%s\": no content follows it" % h["text"][:30],
                                     "add the section content or remove the heading", 2, bx, vps[-1:]))
        prev = h["level"]

    # type sprawl (widest viewport)
    fonts = {k: v for k, v in widest.get("fonts", {}).items() if k}
    if len(fonts) > 3:
        ranked = sorted(fonts.items(), key=lambda kv: -kv[1])
        findings.append(_finding("type-scale", "LOW", "body", "%d font families: %s" % (len(fonts), ", ".join("%s (%d)" % kv for kv in ranked[:6])),
                                 "keep 2: %s for text, %s for headings; map the rest to them" % (ranked[0][0], ranked[1][0]),
                                 2 * (len(fonts) - 3)))
    sizes = widest.get("sizes", {})
    if len(sizes) > 8:
        ranked = sorted(sizes.items(), key=lambda kv: -kv[1])
        common = float(ranked[0][0])
        base = min((14, 16, 18), key=lambda b: abs(b - common))
        scale = {14: (12, 14, 16, 18, 22, 28, 36, 44), 16: (12, 14, 16, 20, 24, 32, 40, 48),
                 18: (14, 16, 18, 22, 28, 36, 44, 56)}[base]
        rare = [k for k, v in sorted(sizes.items(), key=lambda kv: float(kv[0])) if v <= 2]
        findings.append(_finding("type-scale", "LOW", "body", "%d font sizes in use (aim <= 8); used once or twice: %s"
                                 % (len(sizes), ", ".join(r + "px" for r in rare[:8]) or "-"),
                                 "snap to one scale: " + "/".join(str(s) for s in scale) + " px", len(sizes) - 8))

    # palette
    colors = {k: v["n"] for k, v in widest.get("colors", {}).items()}
    clusters, pairs = palette_clusters(colors)
    over = max(0, len(clusters) - 14)
    if over or pairs:
        msg = "%d distinct colours (%d after merging near-duplicates; aim <= 14)" % (len(colors), len(clusters))
        fix = "define tokens (--bg, --text, --muted, --accent, --border ...)"
        if pairs:
            msg += "; near-duplicates: " + ", ".join("%s~%s" % (a, b) for a, b, _ in pairs[:4])
            fix = "merge " + ", ".join("%s into %s" % (a, b) for a, b, _ in pairs[:3]) + "; " + fix
        findings.append(_finding("palette", "LOW", "page", msg, fix, 0.5 * over + min(len(pairs), 6)))

    # spacing rhythm
    spacing = widest.get("spacing", {})
    total = sum(v["n"] for v in spacing.values())
    off = {k: v for k, v in spacing.items() if float(k) >= 4 and 0.5 < float(k) % 4 < 3.5}
    off_n = sum(v["n"] for v in off.values())
    pct = 100.0 * off_n / total if total else 0.0
    if total >= 10 and pct > 15:
        ranked = sorted(off.items(), key=lambda kv: -kv[1]["n"])
        ex = "; ".join("%spx x%d (%s) -> %dpx" % (k, v["n"], v["ex"][0] if v["ex"] else "?", int(round(float(k) / 4) * 4))
                       for k, v in ranked[:3])
        findings.append(_finding("spacing", "LOW", ranked[0][1]["ex"][0].rsplit(" ", 1)[0] if ranked[0][1]["ex"] else "page",
                                 "%.0f%% of margins/paddings/gaps are off the 4 px grid (%d distinct values): %s" % (pct, len(spacing), ex),
                                 "use a spacing scale: 4/8/12/16/24/32/48/64 px (CSS variables)", (pct - 15) / 5.0))

    # static-only: fixed widths that will overflow a phone
    for fw in widest.get("fixedWidth", [])[:6]:
        findings.append(_finding("fixed-width", "MED", fw["sel"], "fixed width %dpx with no max-width: overflows a 375 px phone" % fw["width"],
                                 "max-width:100%% (or width:min(100%%, %dpx))" % fw["width"], 4))
    if static:
        for f in findings:
            f["boxes"] = {}
            f["viewports"] = []

    findings.sort(key=lambda f: (SEVERITY_ORDER[f["severity"]], -f["weight"] * max(1, len(f["viewports"]) ** 0.5), f["selector"]))
    for i, f in enumerate(findings, 1):
        f["rank"] = i
    return findings


def score(findings, static=False):
    """Score = 100 - sum over checks of min(cap, sum of finding weights). Static mode skips layout-only checks."""
    per = {}
    for f in findings:
        per[f["check"]] = per.get(f["check"], 0.0) + f["weight"]
    breakdown = {}
    for check, total in per.items():
        cap = CHECKS[check][1]
        breakdown[check] = round(min(cap, total), 1)
    value = max(0, int(round(100 - sum(breakdown.values()))))
    return value, breakdown


# ------------------------------------------------------------------------------------------------ CLI


def slug_for(target):
    u = urllib.parse.urlparse(target)
    name = (u.netloc + "-" + Path(u.path).stem) if u.scheme in ("http", "https") else Path(u.path or target).stem
    base = re.sub(r"[^a-zA-Z0-9]+", "-", name or "page").strip("-")[:30] or "page"
    return "%s-%s" % (base, hashlib.sha1(target.encode("utf-8")).hexdigest()[:6])


def run(args):
    t0 = time.time()
    viewports = sorted({int(v) for v in args.viewports.split(",") if v.strip()})
    if not viewports or any(v < 200 or v > 4000 for v in viewports):
        raise ValueError("--viewports must be widths between 200 and 4000")
    engine = "static"
    shots = {}
    note = ""
    if not args.static and load_playwright() is not None:
        try:
            measures, pages, (pw, browser) = measure_browser(args.target, viewports, args.timeout, args.offline, None)
            engine = "playwright"
        except FileNotFoundError:
            raise
        except Exception as exc:
            if "no Chromium found" not in str(exc):
                raise
            note = str(exc)
            measures = None
    else:
        measures = None
        if not args.static:
            note = "Playwright not installed: layout checks skipped. Install: " + INSTALL_HINT
    if engine == "playwright":
        try:
            findings = build_findings(measures)
            if not args.no_shots:
                shots_dir = Path(args.shots) if args.shots else Path(tempfile.gettempdir()) / "polish-audit"
                shots = annotate(pages, findings, shots_dir, slug_for(args.target))
        finally:
            browser.close()
            pw.stop()
    else:
        data = measure_static(args.target, args.timeout, args.offline)
        measures = {viewports[-1]: data}
        findings = build_findings(measures)
    value, breakdown = score(findings, engine == "static")
    highs = sum(1 for f in findings if f["severity"] == "HIGH")
    passed = value >= args.fail_under and highs == 0
    m0 = measures[max(measures)]
    report = {
        "tool": "site-polish-audit", "version": VERSION, "target": args.target, "engine": engine,
        "viewports": viewports if engine == "playwright" else [], "seconds": round(time.time() - t0, 2),
        "score": value, "gate": args.fail_under, "pass": passed, "breakdown": breakdown,
        "counts": {"findings": len(findings), "high": highs, "text_elements": m0.get("textCount"),
                   "contrast_unknown_over_images": sum(m.get("contrastUnknown", 0) for m in measures.values())},
        "findings": [{k: v for k, v in f.items() if k != "boxes"} for f in findings],
        "screenshots": {str(k): v for k, v in shots.items()}, "note": note,
        "skipped": sorted(LAYOUT_ONLY) if engine == "static" else [],
    }
    return report


def human(report, top):
    lines = []
    eng = report["engine"]
    vps = ",".join(str(v) for v in report["viewports"]) or "-"
    lines.append("site-polish-audit %s  [%s @ %s px, %.1f s]" % (report["target"], eng, vps, report["seconds"]))
    if report["note"]:
        lines.append("NOTE " + report["note"])
    verdict = "PASS" if report["pass"] else "FAIL"
    lines.append("%s  score %d/100 (gate %d, HIGH findings %d)%s" % (verdict, report["score"], report["gate"], report["counts"]["high"],
                                                                    "  [static: partial score]" if eng == "static" else ""))
    if report["breakdown"]:
        lines.append("  " + "  ".join("%s -%g" % kv for kv in sorted(report["breakdown"].items(), key=lambda kv: -kv[1])))
    shown = report["findings"][:top]
    for f in shown:
        where = ("@" + ",".join(str(v) for v in f["viewports"])) if f["viewports"] else ""
        cnt = " x%d" % f["count"] if f["count"] > 1 else ""
        lines.append("%2d %-4s %-12s %s %s%s" % (f["rank"], f["severity"], f["check"], f["selector"][:48], where, cnt))
        lines.append("   %s" % f["detail"][:150])
        lines.append("   fix: %s" % f["fix"][:150])
    if len(report["findings"]) > top:
        lines.append("   ... %d more (--top %d or --json)" % (len(report["findings"]) - top, len(report["findings"])))
    if report["screenshots"]:
        lines.append("screenshots (red boxes = fix numbers): " + "  ".join(report["screenshots"].values()))
    if report["skipped"]:
        lines.append("skipped without a browser: " + ", ".join(report["skipped"]))
    lines.append("next: " + ("done; keep the design rules in SKILL.md" if report["pass"] else
                             "fix #1-#%d, then re-run until PASS (score >= %d, no HIGH)" % (min(5, len(shown)) or 1, report["gate"])))
    return "\n".join(lines)


def main(argv=None):
    ap = argparse.ArgumentParser(prog="polish_audit.py", description="Render a page, measure polish problems, rank the fixes.",
                                 epilog="Install for the full audit: " + INSTALL_HINT)
    ap.add_argument("target", help="URL (http/https/file) or path to an HTML file")
    ap.add_argument("--viewports", default=",".join(str(v) for v in DEFAULT_VIEWPORTS))
    ap.add_argument("--json", action="store_true", help="machine-readable output")
    ap.add_argument("--score", action="store_true", help="print only the score line and its breakdown")
    ap.add_argument("--top", type=int, default=12, help="fixes to print (default 12)")
    ap.add_argument("--shots", help="folder for annotated screenshots (default: %%TEMP%%/polish-audit)")
    ap.add_argument("--no-shots", action="store_true", help="do not write screenshots")
    ap.add_argument("--static", action="store_true", help="skip the browser: HTML/CSS parse only")
    ap.add_argument("--fail-under", type=int, default=90, help="gate score (default 90)")
    ap.add_argument("--offline", action="store_true", help="block every network request (local files only)")
    ap.add_argument("--timeout", type=float, default=30.0, help="page load timeout in seconds (default 30)")
    ap.add_argument("--version", action="version", version=VERSION)
    try:
        args = ap.parse_args(argv)
    except SystemExit as exc:
        return int(exc.code or 0) if exc.code in (0, None) else 2
    try:
        report = run(args)
    except FileNotFoundError as exc:
        print("error: no such file: %s" % exc, file=sys.stderr)
        return 2
    except ValueError as exc:
        print("error: %s" % exc, file=sys.stderr)
        return 2
    except Exception as exc:  # page failed to load, network error...
        print("error: could not audit %s: %s" % (args.target, str(exc).splitlines()[0][:300] if str(exc) else type(exc).__name__),
              file=sys.stderr)
        return 2
    if args.json:
        print(json.dumps(report, indent=2))
    elif args.score:
        print("%s score %d/100 high=%d  %s" % ("PASS" if report["pass"] else "FAIL", report["score"], report["counts"]["high"],
                                               " ".join("%s=-%g" % kv for kv in sorted(report["breakdown"].items(), key=lambda kv: -kv[1]))))
    else:
        print(human(report, max(1, args.top)))
    return 0 if report["pass"] else 1


if __name__ == "__main__":
    if hasattr(sys.stdout, "reconfigure"):
        try:
            sys.stdout.reconfigure(errors="replace")
        except Exception:  # non-reconfigurable stream
            pass
    sys.exit(main())
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall