amagi-site-diff 0.1.0__py3-none-any.whl

amagi_site_diff/__init__.py

@@ -0,0 +1,3 @@
+"""amagi-site-diff: compare two versions of a website page by page."""
+
+__version__ = "0.1.0"

amagi_site_diff/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

amagi_site_diff/capture.py

@@ -0,0 +1,271 @@
+"""Load pages in headless Chromium and capture screenshot, text, links and element boxes."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from dataclasses import dataclass, field
+
+FREEZE_CSS = """
+*, *::before, *::after {
+  animation-duration: 0s !important; animation-delay: 0s !important;
+  transition-duration: 0s !important; transition-delay: 0s !important;
+  caret-color: transparent !important; scroll-behavior: auto !important;
+}
+"""
+
+# Runs in the page after it settles. Returns everything the diff needs in one round trip.
+PAGE_JS = r"""
+() => {
+  const sx = window.scrollX, sy = window.scrollY;
+  const keep = new Set(['HEADER','NAV','MAIN','SECTION','ARTICLE','ASIDE','FOOTER','H1','H2','H3',
+    'H4','H5','H6','P','A','BUTTON','IMG','PICTURE','VIDEO','svg','LI','UL','OL','FORM','INPUT',
+    'SELECT','TEXTAREA','LABEL','TABLE','TR','TD','TH','FIGURE','FIGCAPTION','BLOCKQUOTE','DIV',
+    'SPAN','STRONG','EM','DL','DT','DD','IFRAME','CANVAS','PRE','CODE']);
+  const part = (el) => {
+    let s = el.tagName.toLowerCase();
+    if (el.id) return s + '#' + el.id;
+    const cls = (el.getAttribute('class') || '').trim().split(/\s+/).filter(Boolean).slice(0, 2);
+    if (cls.length) s += '.' + cls.join('.');
+    const parent = el.parentElement;
+    if (parent) {
+      const same = Array.from(parent.children).filter(c => c.tagName === el.tagName);
+      if (same.length > 1) s += ':nth-of-type(' + (same.indexOf(el) + 1) + ')';
+    }
+    return s;
+  };
+  const describe = (el) => {
+    const parts = [];
+    let node = el;
+    while (node && node.nodeType === 1 && parts.length < 4) {
+      if (node.tagName === 'BODY' || node.tagName === 'HTML') break;
+      parts.unshift(part(node));
+      if (node.id) break;
+      node = node.parentElement;
+    }
+    return parts.join(' > ') || el.tagName.toLowerCase();
+  };
+  const elements = [];
+  for (const el of document.body ? document.body.querySelectorAll('*') : []) {
+    if (elements.length >= 5000) break;
+    if (!keep.has(el.tagName)) continue;
+    const r = el.getBoundingClientRect();
+    if (r.width < 2 || r.height < 2) continue;
+    const cs = getComputedStyle(el);
+    if (cs.visibility === 'hidden' || cs.display === 'none') continue;
+    const text = (el.innerText || el.getAttribute('alt') || el.getAttribute('aria-label') || '')
+      .replace(/\s+/g, ' ').trim().slice(0, 120);
+    elements.push({sel: describe(el), x: Math.round(r.left + sx), y: Math.round(r.top + sy),
+                   w: Math.round(r.width), h: Math.round(r.height), text});
+  }
+  const links = Array.from(document.querySelectorAll('a[href]')).map(a => a.href);
+  const meta = (name) => {
+    const el = document.querySelector('meta[name="' + name + '"]');
+    return el ? (el.getAttribute('content') || '') : null;
+  };
+  const canonical = document.querySelector('link[rel="canonical"]');
+  return {
+    title: document.title || '',
+    description: meta('description'),
+    robots: meta('robots'),
+    canonical: canonical ? canonical.href : null,
+    text: document.body ? document.body.innerText : '',
+    links, elements,
+  };
+}
+"""
+
+# Scroll through the page once so lazy-loaded images are in the full-page screenshot.
+SCROLL_JS = r"""
+async (step) => {
+  const limit = 30000;
+  let y = 0;
+  while (y < Math.min(document.documentElement.scrollHeight, limit)) {
+    window.scrollTo(0, y);
+    await new Promise(r => setTimeout(r, 60));
+    y += step;
+  }
+  window.scrollTo(0, 0);
+}
+"""
+
+
+@dataclass
+class PageCapture:
+    url: str
+    final_url: str | None = None
+    status: int | None = None
+    error: str | None = None
+    title: str = ""
+    description: str | None = None
+    robots: str | None = None
+    canonical: str | None = None
+    text: str = ""
+    links: list[str] = field(default_factory=list)
+    elements: list[dict] = field(default_factory=list)
+    console_errors: list[str] = field(default_factory=list)
+    failed_requests: list[str] = field(default_factory=list)
+    screenshot: bytes | None = None
+
+    @property
+    def ok(self) -> bool:
+        return self.error is None and self.status is not None and self.status < 400
+
+    def problem(self) -> str:
+        if self.error:
+            return self.error
+        if self.status is None:
+            return "no response"
+        return f"HTTP {self.status}"
+
+
+class BrowserMissing(RuntimeError):
+    pass
+
+
+def install_chromium() -> None:
+    """Download Playwright's Chromium build (one time, about 150 MB)."""
+    subprocess.run([sys.executable, "-m", "playwright", "install", "chromium"], check=True)
+
+
+class Capturer:
+    """One headless Chromium, one isolated browser context per side ("a" and "b")."""
+
+    def __init__(self, viewport=(1280, 800), timeout_ms=30000, wait_ms=300, hide=(),
+                 channel=None, full_page=True, scroll=True, auto_install=True, log=None):
+        self.viewport = {"width": viewport[0], "height": viewport[1]}
+        self.timeout_ms = timeout_ms
+        self.wait_ms = wait_ms
+        self.hide = list(hide)
+        self.channel = channel
+        self.full_page = full_page
+        self.scroll = scroll
+        self.auto_install = auto_install
+        self.log = log or (lambda msg: None)
+        self._pw = None
+        self._browser = None
+        self._contexts = {}
+
+    def __enter__(self) -> "Capturer":
+        from playwright.sync_api import sync_playwright
+
+        self._pw = sync_playwright().start()
+        try:
+            self._browser = self._launch()
+            for side in ("a", "b"):
+                self._contexts[side] = self._browser.new_context(
+                    viewport=self.viewport, device_scale_factor=1, reduced_motion="reduce",
+                    color_scheme="light", locale="en-US", timezone_id="UTC",
+                )
+        except BaseException:
+            self.__exit__(None, None, None)
+            raise
+        return self
+
+    def _launch(self):
+        kwargs = {"headless": True}
+        if self.channel:
+            kwargs["channel"] = self.channel
+        try:
+            return self._pw.chromium.launch(**kwargs)
+        except Exception as exc:  # playwright raises its own Error type
+            if "Executable doesn't exist" not in str(exc) or self.channel:
+                raise
+            if not self.auto_install:
+                raise BrowserMissing(
+                    "Chromium for Playwright is not installed. Run: python -m playwright install chromium"
+                ) from exc
+            self.log("Chromium for Playwright not found; downloading it once (about 150 MB)...")
+            install_chromium()
+            return self._pw.chromium.launch(**kwargs)
+
+    @property
+    def browser_version(self) -> str:
+        return self._browser.version if self._browser else ""
+
+    def __exit__(self, *exc) -> None:
+        for ctx in self._contexts.values():
+            try:
+                ctx.close()
+            except Exception:
+                pass
+        self._contexts = {}
+        if self._browser:
+            self._browser.close()
+            self._browser = None
+        if self._pw:
+            self._pw.stop()
+            self._pw = None
+
+    def capture(self, side: str, url: str, screenshot: bool = True) -> PageCapture:
+        cap = PageCapture(url=url)
+        page = self._contexts[side].new_page()
+        page.set_default_timeout(self.timeout_ms)
+
+        def on_console(msg):
+            if msg.type == "error" and len(cap.console_errors) < 50:
+                cap.console_errors.append(msg.text)
+
+        def on_pageerror(err):
+            if len(cap.console_errors) < 50:
+                cap.console_errors.append(f"Uncaught: {err}")
+
+        def on_response(resp):
+            if (resp.status >= 400 and resp.request.resource_type != "document"
+                    and len(cap.failed_requests) < 50):
+                cap.failed_requests.append(f"{resp.status} {resp.url}")
+
+        def on_requestfailed(req):
+            if len(cap.failed_requests) < 50:
+                cap.failed_requests.append(f"failed ({req.failure}) {req.url}")
+
+        page.on("console", on_console)
+        page.on("pageerror", on_pageerror)
+        page.on("response", on_response)
+        page.on("requestfailed", on_requestfailed)
+        try:
+            try:
+                resp = page.goto(url, wait_until="load", timeout=self.timeout_ms)
+            except Exception as exc:
+                cap.error = _short_error(exc)
+                return cap
+            cap.status = resp.status if resp else None
+            cap.final_url = page.url
+            if not cap.ok:
+                return cap
+            _settle(page, min(self.timeout_ms, 10000))
+            css = FREEZE_CSS + "".join(f"{sel} {{ visibility: hidden !important; }}\n" for sel in self.hide)
+            page.add_style_tag(content=css)
+            if self.scroll and self.full_page:
+                page.evaluate(SCROLL_JS, self.viewport["height"])
+                _settle(page, 5000)
+            if self.wait_ms:
+                page.wait_for_timeout(self.wait_ms)
+            info = page.evaluate(PAGE_JS)
+            cap.title = info["title"]
+            cap.description = info["description"]
+            cap.robots = info["robots"]
+            cap.canonical = info["canonical"]
+            cap.text = info["text"]
+            cap.links = info["links"]
+            cap.elements = info["elements"]
+            if screenshot:
+                cap.screenshot = page.screenshot(full_page=self.full_page, animations="disabled", caret="hide")
+        except Exception as exc:
+            cap.error = _short_error(exc)
+        finally:
+            page.close()
+        return cap
+
+
+def _settle(page, timeout_ms: int) -> None:
+    try:
+        page.wait_for_load_state("networkidle", timeout=timeout_ms)
+    except Exception:
+        pass  # long-polling or analytics beacons; the page is as settled as it will get
+
+
+def _short_error(exc: Exception) -> str:
+    text = str(exc).strip()
+    first = text.splitlines()[0] if text else type(exc).__name__
+    return first[:200]

amagi_site_diff/cli.py

@@ -0,0 +1,160 @@
+"""Command line: amagi-site-diff A B [options]."""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import os
+import re
+import sys
+
+from . import __version__
+from .report import render_markdown, summary_line, to_json
+from .runner import Options, run
+from .urls import LocalSite, normalize_path, parse_base
+
+EPILOG = """examples:
+  amagi-site-diff https://example.com https://preview.example.com
+  amagi-site-diff https://example.com https://staging.example.com --path /pricing --no-crawl
+  amagi-site-diff ./dist-old ./dist-new --out diff-report --exit-code
+
+A and B can be base URLs or local folders (a folder is served on 127.0.0.1 for the run).
+Exit codes: 0 done, 1 differences found (only with --exit-code), 2 usage or browser error,
+or a site that never responded.
+"""
+
+
+def _viewport(value: str) -> tuple[int, int]:
+    try:
+        w, h = value.lower().split("x")
+        size = int(w), int(h)
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"expected WIDTHxHEIGHT, got {value!r}") from None
+    if min(size) < 100 or max(size) > 4000:
+        raise argparse.ArgumentTypeError("viewport sides must be between 100 and 4000 px")
+    return size
+
+
+def _positive(value: str) -> int:
+    n = int(value)
+    if n < 1:
+        raise argparse.ArgumentTypeError("must be 1 or more")
+    return n
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="amagi-site-diff",
+        description="Compare two versions of a website page by page: screenshots, pixel diffs "
+                    "and text diffs in one markdown report.",
+        epilog=EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p.add_argument("a", help="before: base URL (https://example.com) or local folder")
+    p.add_argument("b", help="after: base URL (https://preview.example.com) or local folder")
+    p.add_argument("-o", "--out", default="site-diff-report", help="report folder (default: site-diff-report)")
+    p.add_argument("--path", action="append", dest="paths", metavar="PATH",
+                   help="page to start from, relative to the base (repeatable; default: /)")
+    p.add_argument("--no-crawl", action="store_true", help="compare only the --path pages, follow no links")
+    p.add_argument("--max-pages", type=_positive, default=20, help="stop after this many pages (default: 20)")
+    p.add_argument("--keep-query", action="store_true", help="treat ?query variants as separate pages")
+    p.add_argument("--viewport", type=_viewport, default=(1280, 800), metavar="WxH",
+                   help="browser window size (default: 1280x800)")
+    p.add_argument("--viewport-only", action="store_true",
+                   help="screenshot only the first screenful instead of the full page")
+    p.add_argument("--hide", action="append", default=[], metavar="SELECTOR",
+                   help="CSS selector to hide on both sides before the screenshot, e.g. a cookie "
+                        "banner or a live clock (repeatable)")
+    p.add_argument("--wait", type=int, default=300, metavar="MS",
+                   help="extra wait after the page settles, in ms (default: 300)")
+    p.add_argument("--timeout", type=_positive, default=30, metavar="SECONDS",
+                   help="page load timeout (default: 30)")
+    p.add_argument("--threshold", type=int, default=24, metavar="0-255",
+                   help="per-channel colour difference that counts as a changed pixel (default: 24)")
+    p.add_argument("--min-pixels", type=int, default=25, metavar="N",
+                   help="changed pixels needed before a page counts as visually changed (default: 25)")
+    p.add_argument("--channel", choices=["chrome", "msedge"],
+                   help="use an installed Chrome or Edge instead of Playwright's Chromium")
+    p.add_argument("--exit-code", action="store_true", help="exit 1 when any page differs (for CI)")
+    p.add_argument("--version", action="version", version=f"amagi-site-diff {__version__}")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    for stream in (sys.stdout, sys.stderr):
+        with contextlib.suppress(AttributeError, ValueError):
+            stream.reconfigure(encoding="utf-8", errors="replace")
+    args = build_parser().parse_args(argv)
+    if not 0 <= args.threshold <= 255:
+        print("error: --threshold must be between 0 and 255", file=sys.stderr)
+        return 2
+    for path in args.paths or []:
+        # Git Bash on Windows rewrites "/pricing" to "C:/Program Files/Git/pricing" before we see it.
+        if re.match(r"^[A-Za-z]:[\\/]", path):
+            print(f"error: --path {path!r} looks like a Windows file path. If your shell converted "
+                  f"'/page' into it (Git Bash does), write the path without the leading slash "
+                  f"(--path pricing) or set MSYS_NO_PATHCONV=1.", file=sys.stderr)
+            return 2
+
+    from .capture import BrowserMissing, Capturer
+
+    opts = Options(
+        paths=[normalize_path(p) for p in (args.paths or ["/"])],
+        crawl=not args.no_crawl,
+        max_pages=args.max_pages,
+        keep_query=args.keep_query,
+        full_page=not args.viewport_only,
+        color_threshold=args.threshold,
+        min_pixels=max(args.min_pixels, 1),
+    )
+    with contextlib.ExitStack() as stack:
+        bases = []
+        for arg in (args.a, args.b):
+            if os.path.isdir(arg):
+                site = stack.enter_context(LocalSite(arg))
+                bases.append(parse_base(site.url, label=f"{arg} (local folder)"))
+            else:
+                try:
+                    bases.append(parse_base(arg))
+                except ValueError as exc:
+                    print(f"error: {exc}", file=sys.stderr)
+                    return 2
+        base_a, base_b = bases
+        print(f"A: {base_a.label}")
+        print(f"B: {base_b.label}")
+        scope = "the given page(s) only" if args.no_crawl else f"up to {args.max_pages} pages, following links"
+        print(f"Comparing {scope}...")
+        capturer = Capturer(
+            viewport=args.viewport, timeout_ms=args.timeout * 1000, wait_ms=max(args.wait, 0),
+            hide=args.hide, channel=args.channel, full_page=not args.viewport_only,
+            log=lambda m: print(m, file=sys.stderr),
+        )
+        try:
+            stack.enter_context(capturer)
+        except BrowserMissing as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 2
+        except Exception as exc:
+            print(f"error: could not start the browser: {str(exc).splitlines()[0]}", file=sys.stderr)
+            return 2
+        result = run(base_a, base_b, capturer, opts, args.out, log=print)
+
+    report_md = os.path.join(args.out, "report.md")
+    with open(report_md, "w", encoding="utf-8") as fh:
+        fh.write(render_markdown(result))
+    with open(os.path.join(args.out, "report.json"), "w", encoding="utf-8") as fh:
+        fh.write(to_json(result))
+    print(summary_line(result))
+    if result.stopped_at_limit:
+        print(f"Stopped at --max-pages {args.max_pages}; raise it to compare more.")
+    print(f"Report: {os.path.normpath(report_md)}")
+    if result.pages and all(p.status == "broken on both" for p in result.pages):
+        print("error: no page loaded on either side; check the URLs", file=sys.stderr)
+        return 2
+    for label, side in (("A", "a"), ("B", "b")):
+        # Not a single HTTP response: a typo in the URL or a server that is down, not missing pages.
+        if result.pages and all(getattr(p, side).status is None for p in result.pages):
+            print(f"error: {label} never responded ({getattr(result.pages[0], side).problem}); "
+                  f"check the URL", file=sys.stderr)
+            return 2
+    return 1 if (args.exit_code and result.has_changes) else 0

amagi_site_diff/imagediff.py

@@ -0,0 +1,152 @@
+"""Pixel comparison of two screenshots: changed-pixel count, changed regions, diff image."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from PIL import Image, ImageChops, ImageDraw
+
+DIFF_COLOR = (230, 0, 60)
+BOX_COLOR = (0, 110, 255)
+
+
+@dataclass
+class Region:
+    x: int
+    y: int
+    w: int
+    h: int
+    pixels: int = 0  # changed pixels inside the box
+
+    @property
+    def area(self) -> int:
+        return self.w * self.h
+
+    def as_dict(self) -> dict:
+        return {"x": self.x, "y": self.y, "w": self.w, "h": self.h, "pixels": self.pixels}
+
+
+@dataclass
+class ImageDiff:
+    width: int
+    height: int
+    size_a: tuple[int, int]
+    size_b: tuple[int, int]
+    changed_pixels: int
+    regions: list[Region] = field(default_factory=list)
+    mask: Image.Image | None = None
+
+    @property
+    def total_pixels(self) -> int:
+        return self.width * self.height
+
+    @property
+    def ratio(self) -> float:
+        return self.changed_pixels / self.total_pixels if self.total_pixels else 0.0
+
+
+def _pad(img: Image.Image, width: int, height: int) -> Image.Image:
+    if img.size == (width, height):
+        return img
+    canvas = Image.new("RGB", (width, height), (255, 255, 255))
+    canvas.paste(img, (0, 0))
+    return canvas
+
+
+def change_mask(a: Image.Image, b: Image.Image, threshold: int = 24) -> tuple[Image.Image, tuple[int, int]]:
+    """Return an 'L' mask (255 = changed) over the union canvas of a and b.
+
+    A pixel counts as changed when any RGB channel differs by more than threshold
+    (0-255). Area that exists in only one image (a page got taller or wider) is
+    always marked changed.
+    """
+    a = a.convert("RGB")
+    b = b.convert("RGB")
+    width, height = max(a.width, b.width), max(a.height, b.height)
+    pa, pb = _pad(a, width, height), _pad(b, width, height)
+    r, g, bl = ImageChops.difference(pa, pb).split()
+    peak = ImageChops.lighter(ImageChops.lighter(r, g), bl)
+    mask = peak.point(lambda v: 255 if v > threshold else 0)
+    if a.size != b.size:
+        draw = ImageDraw.Draw(mask)
+        for img in (a, b):
+            if img.width < width:
+                draw.rectangle([img.width, 0, width - 1, height - 1], fill=255)
+            if img.height < height:
+                draw.rectangle([0, img.height, width - 1, height - 1], fill=255)
+    return mask, (width, height)
+
+
+def find_regions(mask: Image.Image, cell: int = 16, gap: int = 0, limit: int = 12) -> list[Region]:
+    """Group changed pixels into boxes.
+
+    The mask is reduced to a grid of cell x cell blocks; blocks with any change are
+    joined with their neighbours (including diagonals, and across up to `gap` empty
+    blocks) and each group becomes one bounding box. Largest boxes first.
+    """
+    width, height = mask.size
+    cols, rows = (width + cell - 1) // cell, (height + cell - 1) // cell
+    # Pad to whole cells, then average each cell exactly; one changed pixel still averages to 1.
+    grid = Image.new("L", (cols * cell, rows * cell), 0)
+    grid.paste(mask, (0, 0))
+    grid_img = grid.reduce(cell) if cell > 1 else grid
+    data = grid_img.load()
+    hot = {(cx, cy) for cy in range(rows) for cx in range(cols) if data[cx, cy] > 0}
+    seen: set[tuple[int, int]] = set()
+    regions: list[Region] = []
+    reach = gap + 1
+    for start in sorted(hot):
+        if start in seen:
+            continue
+        stack, members = [start], []
+        seen.add(start)
+        while stack:
+            cx, cy = stack.pop()
+            members.append((cx, cy))
+            for dx in range(-reach, reach + 1):
+                for dy in range(-reach, reach + 1):
+                    nb = (cx + dx, cy + dy)
+                    if nb in hot and nb not in seen:
+                        seen.add(nb)
+                        stack.append(nb)
+        x0 = min(c[0] for c in members) * cell
+        y0 = min(c[1] for c in members) * cell
+        x1 = min((max(c[0] for c in members) + 1) * cell, width)
+        y1 = min((max(c[1] for c in members) + 1) * cell, height)
+        box = mask.crop((x0, y0, x1, y1))
+        tight = box.getbbox()
+        if tight:
+            x0, y0, x1, y1 = x0 + tight[0], y0 + tight[1], x0 + tight[2], y0 + tight[3]
+            box = mask.crop((x0, y0, x1, y1))
+        changed = box.histogram()[255]
+        if changed:
+            regions.append(Region(x0, y0, x1 - x0, y1 - y0, changed))
+    regions.sort(key=lambda r: (-r.pixels, r.y, r.x))
+    return regions[:limit] if limit else regions
+
+
+def compare(a: Image.Image, b: Image.Image, threshold: int = 24, cell: int = 16, limit: int = 12) -> ImageDiff:
+    mask, (width, height) = change_mask(a, b, threshold)
+    changed = mask.histogram()[255]
+    regions = find_regions(mask, cell=cell, limit=limit) if changed else []
+    return ImageDiff(width, height, a.size, b.size, changed, regions, mask)
+
+
+def render_diff(b: Image.Image, diff: ImageDiff) -> Image.Image:
+    """B faded to light grey, changed pixels in red, numbered blue boxes around regions."""
+    base = _pad(b.convert("RGB"), diff.width, diff.height).convert("L")
+    base = base.point(lambda v: int(v * 0.35 + 160)).convert("RGB")
+    out = base
+    if diff.mask is not None and diff.changed_pixels:
+        out = Image.composite(Image.new("RGB", base.size, DIFF_COLOR), base, diff.mask)
+    draw = ImageDraw.Draw(out)
+    for n, r in enumerate(diff.regions, 1):
+        pad = 3
+        box = [max(r.x - pad, 0), max(r.y - pad, 0),
+               min(r.x + r.w + pad, diff.width - 1), min(r.y + r.h + pad, diff.height - 1)]
+        draw.rectangle(box, outline=BOX_COLOR, width=2)
+        label = str(n)
+        tx, ty = box[0], max(box[1] - 14, 0)
+        draw.rectangle([tx, ty, tx + 8 * len(label) + 6, ty + 13], fill=BOX_COLOR)
+        draw.text((tx + 3, ty + 1), label, fill=(255, 255, 255))
+    return out

amagi_site_diff/locate.py

@@ -0,0 +1,58 @@
+"""Name the page element behind a changed region, so the report says what changed, not just where."""
+
+from __future__ import annotations
+
+from .imagediff import Region
+
+# Wrappers that contain almost everything; naming them tells the reader nothing.
+_TOO_BROAD = {"html", "body"}
+
+
+def _box(el: dict) -> tuple[float, float, float, float]:
+    return el["x"], el["y"], el["x"] + el["w"], el["y"] + el["h"]
+
+
+def _tag(el: dict) -> str:
+    return el.get("sel", "").split(" > ")[-1].split("#")[0].split(".")[0].lower()
+
+
+def element_for(region: Region, elements: list[dict], tolerance: float = 4.0) -> dict | None:
+    """Pick the element that best explains a changed region.
+
+    Candidates are the smallest element whose box contains the whole region
+    (within `tolerance` px) and the element whose box overlaps the region best
+    (intersection over union). The container wins unless it is much bigger than
+    the region and some element overlaps it well, which happens when an element
+    changed size: the region is then the union of its old and new boxes.
+    """
+    rx0, ry0, rx1, ry1 = region.x, region.y, region.x + region.w, region.y + region.h
+    container, container_area = None, None
+    overlap, overlap_score = None, 0.0
+    for el in elements:
+        if _tag(el) in _TOO_BROAD:
+            continue
+        x0, y0, x1, y1 = _box(el)
+        area = el["w"] * el["h"]
+        if x0 - tolerance <= rx0 and y0 - tolerance <= ry0 and x1 + tolerance >= rx1 and y1 + tolerance >= ry1:
+            if container_area is None or area < container_area:
+                container, container_area = el, area
+        ix = max(0.0, min(x1, rx1) - max(x0, rx0))
+        iy = max(0.0, min(y1, ry1) - max(y0, ry0))
+        inter = ix * iy
+        if inter:
+            union = area + region.area - inter
+            score = inter / union if union else 0.0
+            if score > overlap_score:
+                overlap, overlap_score = el, score
+    if container is not None and (container_area <= 8 * max(region.area, 1) or overlap_score < 0.3):
+        return container
+    return overlap or container
+
+
+def describe(el: dict | None, max_text: int = 60) -> str:
+    if not el:
+        return "(no element found)"
+    text = (el.get("text") or "").strip()
+    if len(text) > max_text:
+        text = text[: max_text - 3].rstrip() + "..."
+    return f"`{el['sel']}`" + (f' "{text}"' if text else "")