squint-mcp 0.1.0__py3-none-any.whl

squint_mcp/__init__.py

@@ -0,0 +1,6 @@
+"""Squint: an MCP server that finds visual bugs in rendered web pages."""
+
+from importlib.metadata import version
+
+SERVER_NAME = "squint-mcp"
+__version__ = version(SERVER_NAME)

squint_mcp/capture.py

@@ -0,0 +1,154 @@
+"""Capture production: the only module allowed to import `playwright` (ADR-0002)."""
+
+import asyncio
+import io
+import sys
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from mcp.server.mcpserver.exceptions import ToolError
+from PIL import Image, ImageChops
+from playwright.async_api import Browser, Page, Playwright, async_playwright
+from playwright.async_api import Error as PlaywrightError
+from playwright.async_api import TimeoutError as PlaywrightTimeoutError
+
+from squint_mcp import config
+from squint_mcp.models import Capture, Element, Viewport
+
+_JS = Path(__file__).parent / "js"
+_STABILIZE = (_JS / "stabilize.js").read_text(encoding="utf-8")
+_COLLECT_ELEMENTS = (_JS / "collect_elements.js").read_text(encoding="utf-8")
+_FILL_TEXT = (_JS / "fill_text.js").read_text(encoding="utf-8")
+
+
+class BrowserSession:
+    """The one Chromium of a server run: launched on first use, then reused."""
+
+    def __init__(self) -> None:
+        self._playwright: Playwright | None = None
+        self._browser: Browser | None = None
+        self._lock = asyncio.Lock()
+
+    async def browser(self) -> Browser:
+        # The lock keeps two concurrent first calls from launching two browsers.
+        async with self._lock:
+            # A browser that crashed or was closed is launched again.
+            if self._browser is None or not self._browser.is_connected():
+                try:
+                    self._playwright = (
+                        self._playwright or await async_playwright().start()
+                    )
+                    self._browser = await self._playwright.chromium.launch()
+                except PlaywrightError as error:
+                    raise ToolError(
+                        f"Could not launch Chromium: {_first_line(error)}. "
+                        # This interpreter, so the fix reaches the environment
+                        # the server runs in, uvx cache or checkout alike.
+                        "If it is not installed, run: "
+                        f'"{sys.executable}" -m playwright install chromium'
+                    ) from error
+            return self._browser
+
+    async def close(self) -> None:
+        if self._browser is not None:
+            await self._browser.close()
+        if self._playwright is not None:
+            await self._playwright.stop()
+
+
+@asynccontextmanager
+async def browser_lifespan(_: object) -> AsyncGenerator[BrowserSession]:
+    """Server lifespan: the session lives, and its browser dies, with the server."""
+    session = BrowserSession()
+    try:
+        yield session
+    finally:
+        await session.close()
+
+
+def _first_line(error: PlaywrightError) -> str:
+    """Playwright appends call logs and banners; the first line says what failed."""
+    return error.message.splitlines()[0]
+
+
+async def _screenshot(page: Page) -> Image.Image:
+    return Image.open(io.BytesIO(await page.screenshot(full_page=True))).convert("RGB")
+
+
+async def _filled(page: Page, color: str) -> Image.Image:
+    """The page with every glyph painted in `color`."""
+    await page.evaluate(_FILL_TEXT, color)
+    return await _screenshot(page)
+
+
+async def capture(
+    session: BrowserSession, url: str, viewport: Viewport, selector: str
+) -> Capture:
+    """Open `url` in a fresh context, stabilize it and capture it.
+
+    The Capture holds the elements matched by `selector`, which reaches into
+    open shadow roots; `*` is every element of the page.
+    """
+    scheme = urlsplit(url).scheme
+    if scheme not in ("http", "https", "file"):
+        raise ToolError(
+            f'Unsupported URL scheme "{scheme}"; use http://, https:// or file://.'
+        )
+    browser = await session.browser()
+    context = await browser.new_context(
+        viewport={"width": viewport.width, "height": viewport.height},
+        device_scale_factor=1,
+    )
+    try:
+        # The tool's total timeout is the only clock; Playwright's own would race it.
+        context.set_default_timeout(0)
+        page = await context.new_page()
+        try:
+            await page.goto(url, wait_until="load")
+        except PlaywrightError as error:
+            raise ToolError(f"Could not load {url}: {_first_line(error)}") from error
+        await page.evaluate(_STABILIZE)
+        try:
+            await page.wait_for_load_state(
+                "networkidle", timeout=config.NETWORK_IDLE_TIMEOUT_S * 1000
+            )
+            stabilized = True
+        except PlaywrightTimeoutError:
+            # Polling and analytics keep some pages busy forever: capture them anyway.
+            stabilized = False
+        matches = page.locator(f"css={selector}")
+        try:
+            # count() only parses and runs the selector: a failure is its syntax.
+            await matches.count()
+        except PlaywrightError as error:
+            raise ToolError(f'Invalid selector "{selector}".') from error
+        collected = await matches.evaluate_all(
+            _COLLECT_ELEMENTS,
+            {
+                "properties": list(config.CAPTURE_COMPUTED_PROPERTIES),
+                "textLimit": config.TEXT_EXCERPT_MAX_CHARS,
+                "transformMinSizeDiffPx": config.TRANSFORM_MIN_SIZE_DIFF_PX,
+            },
+        )
+        pixels = await _screenshot(page)
+        # After the collector, which reads the page's own styles, and after the
+        # pixels: from here on the text is not painted as the page asked (AD-004).
+        # ponytail: every Capture pays for the three layers, whatever reads them;
+        # take them on request if calls get slow.
+        background = await _filled(page, "transparent")
+        black = await _filled(page, "rgb(0, 0, 0)")
+        white = await _filled(page, "rgb(255, 255, 255)")
+    finally:
+        # A client cancellation keeps cancelling every await: shield the close.
+        await asyncio.shield(context.close())
+    return Capture(
+        viewport=viewport,
+        stabilized=stabilized,
+        elements=[Element.model_validate(element) for element in collected],
+        pixels=pixels,
+        background=background,
+        # Only glyphs differ between the two fills, by how much they cover a pixel.
+        ink=ImageChops.difference(black, white).convert("L"),
+    )

squint_mcp/checks/__init__.py

@@ -0,0 +1,17 @@
+"""The Checks, by name. A Check turns one Capture into Findings, in the order of the
+Capture's elements, and never touches the browser (ADR-0002).
+
+Adding a Check is one module in this package and one entry in `CHECKS`.
+"""
+
+from collections.abc import Callable
+
+from squint_mcp.checks import low_contrast_real, text_clipped
+from squint_mcp.models import Capture, Finding
+
+Check = Callable[[Capture], list[Finding]]
+
+CHECKS: dict[str, Check] = {
+    "text-clipped": text_clipped.check,
+    "low-contrast-real": low_contrast_real.check,
+}

squint_mcp/checks/low_contrast_real.py

@@ -0,0 +1,166 @@
+"""The `low-contrast-real` Check: text too close in colour to what is painted behind it.
+
+The background is read from the pixels, not from `background-color`, so it is right
+over an image or a gradient (WCAG 2.2 SC 1.4.3).
+"""
+
+import math
+import re
+
+from squint_mcp import config
+from squint_mcp.models import Capture, Element, Evidence, Finding, Viewport
+from squint_mcp.vision import text_backgrounds
+
+type Rgb = tuple[int, int, int]
+
+# The styles that explain the contrast. `background-color` is what a tool that
+# reads only the DOM would have compared the text with, and `color` is what it
+# would have taken for the text where the fill paints the glyphs in another colour.
+_EVIDENCE_PROPERTIES = (
+    "color",
+    "-webkit-text-fill-color",
+    "background-color",
+    "background-image",
+    "font-size",
+    "font-weight",
+)
+
+# How Chromium serializes a computed sRGB colour.
+# ponytail: a colour in another space (`oklch(...)`, `color(display-p3 ...)`) keeps
+# its own syntax and the element is skipped; convert it if such text gets common.
+_COLOR = re.compile(r"rgba?\((\d+), (\d+), (\d+)(?:, ([\d.]+))?\)")
+
+
+def _luminance(color: Rgb) -> float:
+    """The relative luminance of WCAG 2.2."""
+
+    def linear(channel: int) -> float:
+        value = channel / 255
+        return value / 12.92 if value <= 0.04045 else ((value + 0.055) / 1.055) ** 2.4
+
+    red, green, blue = color
+    return 0.2126 * linear(red) + 0.7152 * linear(green) + 0.0722 * linear(blue)
+
+
+def _contrast(one: Rgb, other: Rgb) -> float:
+    """The contrast ratio of WCAG 2.2, from 1 to 21."""
+    lighter, darker = sorted((_luminance(one), _luminance(other)), reverse=True)
+    return (lighter + 0.05) / (darker + 0.05)
+
+
+def _over(color: Rgb, alpha: float, behind: Rgb) -> Rgb:
+    """`color` at `alpha` as seen over `behind`."""
+    red, green, blue = (
+        math.floor(alpha * front + (1 - alpha) * back + 0.5)
+        for front, back in zip(color, behind, strict=True)
+    )
+    return red, green, blue
+
+
+def _hex(color: Rgb) -> str:
+    return "#{:02x}{:02x}{:02x}".format(*color)
+
+
+def _worst_part(element: Element, capture: Capture) -> tuple[float, Rgb, Rgb] | None:
+    """The contrast of the least readable part of the element's own text, with the
+    text colour and the background there; None when the element has no text to judge.
+
+    Text covered by another element's text is judged on that text's ink: the ink
+    layer does not say whose glyph a pixel belongs to.
+    """
+    if not element.own_text:
+        return None
+    # A faded text is blended with what is behind its faded ancestor, which the
+    # Capture does not hold: its real colour is not known.
+    if element.opacity < 1:
+        return None
+    color = _COLOR.fullmatch(element.computed["-webkit-text-fill-color"])
+    if color is None:
+        return None
+    text: Rgb = (int(color[1]), int(color[2]), int(color[3]))
+    alpha = 1.0 if color[4] is None else float(color[4])
+    # Text made transparent is hidden on purpose, as when an image replaces it.
+    if alpha == 0:
+        return None
+    behind = text_backgrounds(capture.background, capture.ink, element.own_text_boxes)
+    if not behind:
+        return None
+    # A translucent text is as dark as what shows through it.
+    parts = sorted(
+        (_contrast(seen, background), count, seen, background)
+        for count, background in behind
+        for seen in (_over(text, alpha, background),)
+    )
+    total = sum(count for _, count, _, _ in parts)
+    # From the least readable colour up, the first one at which the share of the
+    # text reached is the worst part. In integers: "exactly a tenth" is exact.
+    reached = 0
+    for ratio, count, seen, background in parts:
+        reached += count
+        if reached * 100 >= config.LOW_CONTRAST_WORST_PART_PERCENT * total:
+            return ratio, seen, background
+    raise AssertionError("the whole text is always reached")
+
+
+def _required_ratio(element: Element) -> float:
+    font_size = float(element.computed["font-size"].removesuffix("px"))
+    bold = float(element.computed["font-weight"]) >= config.BOLD_MIN_WEIGHT
+    large = font_size >= config.LARGE_TEXT_MIN_PX or (
+        bold and font_size >= config.LARGE_BOLD_TEXT_MIN_PX
+    )
+    return config.CONTRAST_MIN_RATIO_LARGE if large else config.CONTRAST_MIN_RATIO
+
+
+def _finding(
+    element: Element,
+    viewport: Viewport,
+    ratio: float,
+    required: float,
+    text: Rgb,
+    background: Rgb,
+) -> Finding:
+    # WCAG: a ratio is not rounded up to meet a threshold, so 4.478 is shown as 4.47.
+    shown = math.floor(ratio * 100) / 100
+    major = ratio < config.LOW_CONTRAST_MAJOR_BELOW_RATIO
+    return Finding(
+        check="low-contrast-real",
+        category="a11y",
+        severity="major" if major else "minor",
+        message=(
+            f"Text contrast {shown:.2f}:1 against the painted background "
+            f"{_hex(background)} is below the {required:g}:1 minimum"
+        ),
+        selector=element.selector,
+        text=element.text,
+        box=element.box,
+        viewport=viewport,
+        evidence=Evidence(
+            computed={name: element.computed[name] for name in _EVIDENCE_PROPERTIES},
+            measured={
+                "contrastRatio": shown,
+                "requiredRatio": required,
+                "textColor": _hex(text),
+                "sampledBackground": _hex(background),
+            },
+        ),
+        suggestion=(
+            "Change the text colour or put a solid background behind the text "
+            f"to reach {required:g}:1"
+        ),
+        source="WCAG 2.2 SC 1.4.3",
+    )
+
+
+def check(capture: Capture) -> list[Finding]:
+    findings: list[Finding] = []
+    for element in capture.elements:
+        worst = _worst_part(element, capture)
+        if worst is None:
+            continue
+        ratio, text, background = worst
+        required = _required_ratio(element)
+        if ratio < required:
+            findings.append(
+                _finding(element, capture.viewport, ratio, required, text, background)
+            )
+    return findings

squint_mcp/checks/text_clipped.py

@@ -0,0 +1,133 @@
+"""The `text-clipped` Check: text cut off horizontally by its own box."""
+
+from PIL import Image
+
+from squint_mcp import config
+from squint_mcp.models import Box, Capture, Element, Evidence, Finding, Viewport
+from squint_mcp.vision import is_flat
+
+# The styles that explain the cut.
+_EVIDENCE_PROPERTIES = (
+    "overflow-x",
+    "white-space",
+    "text-overflow",
+    "width",
+    "font-size",
+)
+
+
+def _overflow_px(element: Element) -> int:
+    return element.scroll_width - element.client_width
+
+
+def _is_resized(element: Element) -> bool:
+    """Whether the element is painted at another size than it is laid out.
+
+    `box` is painted and the box model is layout (ADR-0003): the two differ
+    under a transform that scales, rotates or skews, on the element or on an
+    ancestor. Scroll and client width are layout pixels, so the cut has no
+    known place in the painted ones.
+    """
+    model = element.box_model
+    layout_w = (
+        model.content.w
+        + model.padding.left
+        + model.padding.right
+        + model.border.left
+        + model.border.right
+    )
+    layout_h = (
+        model.content.h
+        + model.padding.top
+        + model.padding.bottom
+        + model.border.top
+        + model.border.bottom
+    )
+    # ponytail: a mirror or a half turn keeps both sizes and is read as no
+    # transform, so the strip is read at the painted start of the text. The text
+    # is still cut there; compare positions too if such a Finding proves wrong.
+    return (
+        abs(element.box.w - layout_w) >= config.TRANSFORM_MIN_SIZE_DIFF_PX
+        or abs(element.box.h - layout_h) >= config.TRANSFORM_MIN_SIZE_DIFF_PX
+    )
+
+
+def _padding_right(element: Element) -> float:
+    """The right edge of the padding box, in page coordinates."""
+    return element.box.x + element.box_model.border.left + element.client_width
+
+
+def _edge_strip(element: Element) -> Box:
+    """The part of the padding box within one font-size of its right edge.
+
+    A cut glyph is painted there. One font-size is wider than any gap between
+    two letters, so the strip cannot fall entirely between glyphs.
+    """
+    border = element.box_model.border
+    font_size = float(element.computed["font-size"].removesuffix("px"))
+    right = _padding_right(element)
+    left = max(element.box.x + border.left, right - font_size)
+    return Box(
+        x=left,
+        y=element.box.y + border.top,
+        w=right - left,
+        h=element.box.h - border.top - border.bottom,
+    )
+
+
+def _is_clipped(element: Element, pixels: Image.Image) -> bool:
+    computed = element.computed
+    return (
+        element.own_text
+        # `auto` and `scroll` leave the text reachable by scrolling.
+        and computed["overflow-x"] in ("hidden", "clip")
+        # An ellipsis is a cut the author asked for.
+        and computed["text-overflow"] == "clip"
+        # Right-to-left text is cut on the other edge.
+        and computed["direction"] == "ltr"
+        # Hidden text is not cut for anyone, whatever is painted behind it.
+        and computed["visibility"] == "visible"
+        and _overflow_px(element) >= config.TEXT_CLIPPED_MIN_OVERFLOW_PX
+        # Before the pixels: the strip is only where layout and paint coincide.
+        and not _is_resized(element)
+        # scrollWidth also counts an overflowing child: the text itself has to
+        # pass the edge.
+        and element.own_text_right is not None
+        and element.own_text_right > _padding_right(element)
+        # The DOM says text overflows; the pixels say whether any of it is seen
+        # being cut. A strip of one colour is hidden text or blank overflow.
+        and not is_flat(pixels, _edge_strip(element))
+    )
+
+
+def _finding(element: Element, viewport: Viewport) -> Finding:
+    overflow_px = _overflow_px(element)
+    major = overflow_px >= config.TEXT_CLIPPED_MAJOR_OVERFLOW_PX
+    return Finding(
+        check="text-clipped",
+        category="visual-bug",
+        severity="major" if major else "minor",
+        message=f"Text clipped by {overflow_px}px by its container width",
+        selector=element.selector,
+        text=element.text,
+        box=element.box,
+        viewport=viewport,
+        evidence=Evidence(
+            computed={name: element.computed[name] for name in _EVIDENCE_PROPERTIES},
+            measured={
+                "overflowPx": overflow_px,
+                "scrollWidth": element.scroll_width,
+                "clientWidth": element.client_width,
+            },
+        ),
+        suggestion="Allow wrapping or reduce font-size at this width",
+        source="Squint heuristic",
+    )
+
+
+def check(capture: Capture) -> list[Finding]:
+    return [
+        _finding(element, capture.viewport)
+        for element in capture.elements
+        if _is_clipped(element, capture.pixels)
+    ]

squint_mcp/config.py

@@ -0,0 +1,111 @@
+"""Thresholds and defaults, each with its source cited."""
+
+# Source: docs/SPEC.md, Further Notes: a single desktop size, as in the draft's example.
+DEFAULT_VIEWPORT_WIDTH = 1440
+DEFAULT_VIEWPORT_HEIGHT = 900
+
+# Source: docs/SPEC.md, Tools: "a total timeout of 30s with a clear error".
+TOTAL_TIMEOUT_S = 30.0
+
+# Source: docs/SPEC.md, Stabilization: "networkidle with a timeout of about 3s".
+NETWORK_IDLE_TIMEOUT_S = 3.0
+
+# Source: Squint default. docs/SPEC.md asks for "a margin around the element";
+# 16px shows the surroundings without doubling the size of a small crop.
+CROP_MARGIN_PX = 16
+
+# Source: docs/SPEC.md, Images: "downscaled to about 512px on its longest side".
+CROP_MAX_SIDE_PX = 512
+
+# Source: Squint default. On text over a flat fill, the three most frequent colours
+# are the fill, the text and the dominant anti-aliasing blend.
+SAMPLED_COLORS_MAX = 3
+
+# Source: Squint default, measured for issue #4. Counting the colours of a region
+# where every pixel has its own takes about 2 microseconds a pixel: 15s for an
+# element of 1440x5000. At 512x512 it stays under half a second, and the contrast
+# of as many colours behind a text takes about two. A larger region is sampled
+# down to that many pixels first.
+COLOR_COUNT_MAX_PIXELS = 512 * 512
+
+# Source: Squint default. Chromium resolves 350+ properties; these are the ones that
+# decide how a box and its text are painted. Margin, border and padding are reported
+# in the box model instead.
+INSPECT_COMPUTED_PROPERTIES = (
+    "display",
+    "position",
+    "box-sizing",
+    "width",
+    "height",
+    "color",
+    "background-color",
+    "background-image",
+    "opacity",
+    "visibility",
+    "overflow-x",
+    "overflow-y",
+    "font-family",
+    "font-size",
+    "font-weight",
+    "line-height",
+    "letter-spacing",
+    "text-align",
+    "text-overflow",
+    "white-space",
+)
+
+# Source: Squint default. What a Capture collects for every element: the inspect
+# properties plus `direction`, which tells a Check on which edge text is cut, and
+# `-webkit-text-fill-color`, the colour that paints the glyphs: that of `color`
+# unless the page sets it.
+CAPTURE_COMPUTED_PROPERTIES = (
+    *INSPECT_COMPUTED_PROPERTIES,
+    "direction",
+    "-webkit-text-fill-color",
+)
+
+# Source: docs/SPEC.md, Images: "At most five crops per call".
+MAX_CROPS = 5
+
+# Source: docs/SPEC.md, Finding: "visible text excerpt, ~40 chars".
+TEXT_EXCERPT_MAX_CHARS = 40
+
+# Source: Squint default. scrollWidth and clientWidth are rounded integers, so a
+# difference of 1px can be rounding alone.
+TEXT_CLIPPED_MIN_OVERFLOW_PX = 2
+
+# Source: Squint default. A cut of 8px or more takes a glyph or most of one at body
+# sizes and is `major`; a smaller one is `minor`.
+TEXT_CLIPPED_MAJOR_OVERFLOW_PX = 8
+
+# Source: docs/adr/0003. An element whose painted size differs from its layout size
+# by this much is under a transform. The collector is passed the same value.
+TRANSFORM_MIN_SIZE_DIFF_PX = 1
+
+# Source: WCAG 2.2 SC 1.4.3 Contrast (Minimum): "a contrast ratio of at least 4.5:1".
+CONTRAST_MIN_RATIO = 4.5
+
+# Source: WCAG 2.2 SC 1.4.3: "Large-scale text [has] a contrast ratio of at least 3:1".
+CONTRAST_MIN_RATIO_LARGE = 3.0
+
+# Source: WCAG 2.2, "large scale": at least 18 point, which is 24 CSS pixels.
+LARGE_TEXT_MIN_PX = 24.0
+
+# Source: WCAG 2.2, "large scale": at least 14 point bold, "typically 18.66px".
+LARGE_BOLD_TEXT_MIN_PX = 18.66
+
+# Source: CSS Fonts: the `bold` keyword computes to a font-weight of 700.
+BOLD_MIN_WEIGHT = 700
+
+# Source: Squint default. 3:1 is the lowest ratio WCAG accepts for any text: under
+# it the Finding is `major`, from it up to the required ratio it is `minor`.
+LOW_CONTRAST_MAJOR_BELOW_RATIO = 3.0
+
+# Source: Squint default. Over a background that varies, the worst tenth of the
+# text decides: one glyph in a word of ten. A title that half disappears is caught
+# and a few stray pixels of a photo are not.
+LOW_CONTRAST_WORST_PART_PERCENT = 10
+
+# Source: Squint default. Ink runs from 0 to 255: a pixel at least half covered by
+# a glyph is text, a fainter anti-aliased edge is background.
+TEXT_INK_MIN = 128