squint-mcp 0.1.0__tar.gz

squint_mcp-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.agents/
+.claude/
+.cursor/
+.windsurf/
+__pycache__/
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/

squint_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Squint stays on 0.x while the Finding schema is still changing: removing or renaming a Finding field, a tool or a tool parameter is a breaking change. Adding a Check or changing a threshold is not breaking, but is always recorded here.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-08
+
+First release, on PyPI as `squint-mcp`.
+
+### Added
+
+- MCP server over stdio, started with the `squint-mcp` command.
+- `ping` tool: returns the server name and version and echoes an optional `message`.
+- `inspect_element` tool: for one element of a page (`url`, `selector`, optional `viewport`), returns its computed styles, box model, the colours sampled from its pixels, whether the page stabilized, and a crop.
+- `detect_visual_bugs` tool: for a page (`url`, optional `viewports`, optional `checks`), runs Checks on one Capture per viewport and returns Findings ordered by severity, whether each viewport stabilized, and up to five crops. Each Finding carries a selector that is unique on the page and works in `inspect_element`.
+- `text-clipped` Check: reports text cut off horizontally by its own box (`overflow-x: hidden` or `clip`), confirmed in the pixels. A cut of 8px or more is `major`, a smaller one `minor`; a cut of 1px is not reported.
+- `low-contrast-real` Check (WCAG 2.2 SC 1.4.3): reports text whose contrast is below 4.5:1, or 3:1 for large text (24px, or 18.66px bold), against the background painted behind it. The background is sampled from the pixels, so it is right over an image or a gradient; where it varies, the worst tenth of the text decides. A ratio under 3:1 is `major`, any other `minor`. Text with an `opacity` below 1, on itself or on an ancestor, is not judged.
+- `evidence.measured` of a Finding can hold strings besides numbers: `low-contrast-real` reports `textColor` and `sampledBackground` as `#rrggbb`.
+- Findings of the same severity and viewport come in document order whatever the Check that reported them, and two Findings on one element in the order of their Check names. The order of `checks` does not change the result.
+- `inspect_element` and the `low-contrast-real` Check stay fast on a large element painted in millions of colours, such as a long photo-heavy page: an element, or the text of an element, of more than 262,144 pixels (512x512) is sampled down to that many before its colours are counted, so `sampledColors` and the contrast of such an element come from the sample. Smaller ones are counted whole, as before ([#4](https://github.com/sh4wty1/squint-mcp/issues/4)).

squint_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucas Fassi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

squint_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.5
+Name: squint-mcp
+Version: 0.1.0
+Summary: MCP server that finds visual bugs in a rendered web page by crossing DOM/CSS with pixels, without a baseline.
+Project-URL: Repository, https://github.com/sh4wty1/squint-mcp
+Project-URL: Issues, https://github.com/sh4wty1/squint-mcp/issues
+Project-URL: Changelog, https://github.com/sh4wty1/squint-mcp/blob/main/CHANGELOG.md
+Author: Lucas Fassi
+License-Expression: MIT
+License-File: LICENSE
+Keywords: accessibility,mcp,playwright,visual-testing,wcag
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.12
+Requires-Dist: mcp>=2.3.0
+Requires-Dist: pillow>=12.3.0
+Requires-Dist: playwright>=1.63.0
+Requires-Dist: pydantic>=2.13.5
+Description-Content-Type: text/markdown
+
+# Squint
+
+Squint is an MCP server that examines a rendered web page by crossing what the browser reports (DOM/CSS) with what is actually painted (pixels), and reports the visual problems it finds without needing a baseline.
+
+It is built for coding agents that have just produced UI and need to know whether the page actually looks right: which element is broken, and what the evidence is.
+
+## Install
+
+Requires [uv](https://docs.astral.sh/uv/). uv installs Python 3.12 for you if it is missing. Two steps:
+
+```bash
+uvx --from squint-mcp playwright install chromium   # the browser Squint drives
+uvx squint-mcp                                       # the server
+```
+
+The first step goes through `squint-mcp` so the Chromium downloaded is the one its Playwright expects; uv warns that `playwright` comes from a dependency, which is expected. On Linux, add `--with-deps` to also install the system libraries Chromium needs.
+
+The server speaks MCP over stdio, so started by hand it just waits for a client. Register it in your MCP client instead:
+
+```json
+{
+  "mcpServers": {
+    "squint": {
+      "command": "uvx",
+      "args": ["squint-mcp"]
+    }
+  }
+}
+```
+
+In Claude Code: `claude mcp add squint -- uvx squint-mcp`.
+
+Then call `ping` to confirm the connection.
+
+## Tools
+
+The server exposes three tools:
+
+| Tool | Input | Output |
+| --- | --- | --- |
+| `ping` | `message` (optional string) | server `name`, `version`, and the echoed `message` |
+| `inspect_element` | `url`, `selector`, `viewport` (optional) | one element's computed styles, box model, sampled colours, `stabilized`, and a crop |
+| `detect_visual_bugs` | `url`, `viewports` (optional), `checks` (optional) | Findings ordered by severity, `stabilized` per viewport, and up to five crops |
+
+`detect_visual_bugs` runs two Checks: `text-clipped` (text cut off by its own box) and `low-contrast-real` (text whose contrast against the background sampled from the pixels is below WCAG 2.2 SC 1.4.3, so it is right over images and gradients). See [`docs/SPEC.md`](https://github.com/sh4wty1/squint-mcp/blob/main/docs/SPEC.md) for the v0.1 specification and [`CHANGELOG.md`](https://github.com/sh4wty1/squint-mcp/blob/main/CHANGELOG.md) for what each release contains.
+
+## Development
+
+Run from a checkout:
+
+```bash
+git clone https://github.com/sh4wty1/squint-mcp.git
+cd squint-mcp
+uv sync
+uv run playwright install chromium   # the tests drive a real Chromium
+uv run squint-mcp
+```
+
+To point an MCP client at the checkout, use `"command": "uv"` with `"args": ["run", "--directory", "/path/to/squint-mcp", "squint-mcp"]`.
+
+One command each:
+
+```bash
+uv run pyright              # typecheck (strict)
+uv run ruff check           # lint
+uv run ruff format --check  # format check
+uv run pytest               # tests
+```
+
+Tests drive the server through an in-memory MCP client, the same surface a real client uses. See [`CONTRIBUTING.md`](https://github.com/sh4wty1/squint-mcp/blob/main/CONTRIBUTING.md).
+
+## Documentation
+
+- [`CONTEXT.md`](https://github.com/sh4wty1/squint-mcp/blob/main/CONTEXT.md): domain glossary (Capture, Check, Finding, Profile, Audit)
+- [`docs/SPEC.md`](https://github.com/sh4wty1/squint-mcp/blob/main/docs/SPEC.md): v0.1 specification
+- [`docs/adr/`](https://github.com/sh4wty1/squint-mcp/tree/main/docs/adr): architecture decision records
+
+## License
+
+[MIT](https://github.com/sh4wty1/squint-mcp/blob/main/LICENSE)

squint_mcp-0.1.0/README.md

@@ -0,0 +1,80 @@
+# Squint
+
+Squint is an MCP server that examines a rendered web page by crossing what the browser reports (DOM/CSS) with what is actually painted (pixels), and reports the visual problems it finds without needing a baseline.
+
+It is built for coding agents that have just produced UI and need to know whether the page actually looks right: which element is broken, and what the evidence is.
+
+## Install
+
+Requires [uv](https://docs.astral.sh/uv/). uv installs Python 3.12 for you if it is missing. Two steps:
+
+```bash
+uvx --from squint-mcp playwright install chromium   # the browser Squint drives
+uvx squint-mcp                                       # the server
+```
+
+The first step goes through `squint-mcp` so the Chromium downloaded is the one its Playwright expects; uv warns that `playwright` comes from a dependency, which is expected. On Linux, add `--with-deps` to also install the system libraries Chromium needs.
+
+The server speaks MCP over stdio, so started by hand it just waits for a client. Register it in your MCP client instead:
+
+```json
+{
+  "mcpServers": {
+    "squint": {
+      "command": "uvx",
+      "args": ["squint-mcp"]
+    }
+  }
+}
+```
+
+In Claude Code: `claude mcp add squint -- uvx squint-mcp`.
+
+Then call `ping` to confirm the connection.
+
+## Tools
+
+The server exposes three tools:
+
+| Tool | Input | Output |
+| --- | --- | --- |
+| `ping` | `message` (optional string) | server `name`, `version`, and the echoed `message` |
+| `inspect_element` | `url`, `selector`, `viewport` (optional) | one element's computed styles, box model, sampled colours, `stabilized`, and a crop |
+| `detect_visual_bugs` | `url`, `viewports` (optional), `checks` (optional) | Findings ordered by severity, `stabilized` per viewport, and up to five crops |
+
+`detect_visual_bugs` runs two Checks: `text-clipped` (text cut off by its own box) and `low-contrast-real` (text whose contrast against the background sampled from the pixels is below WCAG 2.2 SC 1.4.3, so it is right over images and gradients). See [`docs/SPEC.md`](https://github.com/sh4wty1/squint-mcp/blob/main/docs/SPEC.md) for the v0.1 specification and [`CHANGELOG.md`](https://github.com/sh4wty1/squint-mcp/blob/main/CHANGELOG.md) for what each release contains.
+
+## Development
+
+Run from a checkout:
+
+```bash
+git clone https://github.com/sh4wty1/squint-mcp.git
+cd squint-mcp
+uv sync
+uv run playwright install chromium   # the tests drive a real Chromium
+uv run squint-mcp
+```
+
+To point an MCP client at the checkout, use `"command": "uv"` with `"args": ["run", "--directory", "/path/to/squint-mcp", "squint-mcp"]`.
+
+One command each:
+
+```bash
+uv run pyright              # typecheck (strict)
+uv run ruff check           # lint
+uv run ruff format --check  # format check
+uv run pytest               # tests
+```
+
+Tests drive the server through an in-memory MCP client, the same surface a real client uses. See [`CONTRIBUTING.md`](https://github.com/sh4wty1/squint-mcp/blob/main/CONTRIBUTING.md).
+
+## Documentation
+
+- [`CONTEXT.md`](https://github.com/sh4wty1/squint-mcp/blob/main/CONTEXT.md): domain glossary (Capture, Check, Finding, Profile, Audit)
+- [`docs/SPEC.md`](https://github.com/sh4wty1/squint-mcp/blob/main/docs/SPEC.md): v0.1 specification
+- [`docs/adr/`](https://github.com/sh4wty1/squint-mcp/tree/main/docs/adr): architecture decision records
+
+## License
+
+[MIT](https://github.com/sh4wty1/squint-mcp/blob/main/LICENSE)

squint_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[project]
+name = "squint-mcp"
+version = "0.1.0"
+description = "MCP server that finds visual bugs in a rendered web page by crossing DOM/CSS with pixels, without a baseline."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+authors = [{ name = "Lucas Fassi" }]
+keywords = ["mcp", "visual-testing", "accessibility", "playwright", "wcag"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "mcp>=2.3.0",
+    "pillow>=12.3.0",
+    "playwright>=1.63.0",
+    "pydantic>=2.13.5",
+]
+
+[project.urls]
+Repository = "https://github.com/sh4wty1/squint-mcp"
+Issues = "https://github.com/sh4wty1/squint-mcp/issues"
+Changelog = "https://github.com/sh4wty1/squint-mcp/blob/main/CHANGELOG.md"
+
+[project.scripts]
+squint-mcp = "squint_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "CHANGELOG.md"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/squint_mcp"]
+
+[tool.pyright]
+include = ["src", "tests"]
+typeCheckingMode = "strict"
+
+[tool.ruff]
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+    "pyright>=1.1.414",
+    "pytest>=9.1.1",
+    "ruff>=0.16.10",
+]

squint_mcp-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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