reading_order.py

#!/usr/bin/env python3
"""
reading_order.py

Scan a webpage with Playwright and produce a reading-order report based on the
accessibility tree snapshot. Outputs a console summary and an HTML file that
lists the accessible nodes (headings, links, buttons, paragraphs, etc.) in the
order a screen reader would generally encounter them.

Usage:
  python reading_order.py https://example.com --output report.html

Notes:
 - Requires Playwright for Python. See README.md for install steps.
 - The script uses Playwright's accessibility snapshot which approximates the
   accessibility tree used by assistive technologies. It may not exactly match
   every screen reader's output but is a useful visual representation.
"""

from __future__ import annotations

import argparse
import html
import json
import os
import sys
from typing import Any, Dict, List, Optional
from urllib.parse import urlparse

from playwright.sync_api import sync_playwright


INTERESTING_ROLES = {
    "heading",
    "link",
    "button",
    "list",
    "listitem",
    "article",
    "region",
    "navigation",
    "table",
    "cell",
    "row",
    "textbox",
    "radio",
    "checkbox",
    # text-like roles
    "text",
    "static_text",
}


def flatten_accessibility_tree(node: Dict[str, Any], out: List[Dict[str, Any]], depth: int = 0) -> None:
    """Traverse Playwright accessibility snapshot in order and collect nodes.

    We keep nodes that are not hidden and that either have a visible name or are
    one of INTERESTING_ROLES. The traversal order approximates reading order.
    """
    if not isinstance(node, dict):
        return

    hidden = node.get("hidden") or node.get("ignored")
    name = node.get("name")
    role = node.get("role")

    # Skip hidden/ignored nodes.
    if hidden:
        pass
    else:
        keep = False
        if role in INTERESTING_ROLES:
            keep = True
        if name and name.strip():
            keep = True

        if keep:
            item = {
                "role": role or "",
                "name": name or "",
                "value": node.get("value") or "",
                "depth": depth,
                "props": {k: v for k, v in node.items() if k not in ("children",)},
            }
            out.append(item)

    for child in node.get("children", []) or []:
        flatten_accessibility_tree(child, out, depth + 1)


def scan_page(url: str, output_html: str, headful: bool = False, screenshot_path: str | None = None) -> Dict[str, Any]:
    """Capture accessibility snapshot, a DOM-based reading-order list, and a screenshot.

    Returns a dictionary with keys: items (list), accessibility (snapshot), screenshot (path).
    """
    with sync_playwright() as pw:
        browser = pw.chromium.launch(headless=not headful)
        ua = (
            "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
            "AppleWebKit/537.36 (KHTML, like Gecko) "
            "Chrome/126.0.0.0 Safari/537.36"
        )
        context = browser.new_context(
            viewport={"width": 1280, "height": 800},
            ignore_https_errors=True,
            user_agent=ua,
        )
        page = context.new_page()
        # Robust navigation: try networkidle, then load, then domcontentloaded
        nav_ok = False
        for wait_state, to in (("networkidle", 90000), ("load", 90000), ("domcontentloaded", 90000)):
            try:
                page.goto(url, wait_until=wait_state, timeout=to)
                nav_ok = True
                break
            except Exception:
                nav_ok = False
        if not nav_ok:
            # Last resort: try navigate without wait and then wait for any load state briefly
            try:
                page.goto(url, timeout=90000)
                try:
                    page.wait_for_load_state("domcontentloaded", timeout=30000)
                except Exception:
                    pass
            except Exception:
                pass

        # Accessibility snapshot
        try:
            accessibility = page.accessibility.snapshot({"interestingOnly": False})
        except Exception:
            accessibility = {}

        # Small delay to allow initial paint if needed
        try:
            page.wait_for_timeout(500)
        except Exception:
            pass

        # Capture page size for overlay scaling
        try:
            page_width = page.evaluate("() => document.documentElement.scrollWidth") or 0
            page_height = page.evaluate("() => document.documentElement.scrollHeight") or 0
        except Exception:
            page_width = 0
            page_height = 0

        # Take a full page screenshot with robust fallbacks
        if not screenshot_path:
            screenshot_path = "reading_order_snapshot.png"

        def _try_shot(p) -> bool:
            try:
                p.screenshot(path=screenshot_path, full_page=True)
                return True
            except Exception:
                try:
                    p.screenshot(path=screenshot_path, full_page=False)
                    return True
                except Exception:
                    return False

        ok = _try_shot(page)
        if not ok:
            # If page closed or failed, try creating a fresh page and retry once
            try:
                if page.is_closed():
                    page = context.new_page()
                page.goto(url, timeout=30000)
                _try_shot(page)
            except Exception:
                pass

        # Collect DOM-based items including focusables across all frames
        js = r"""
                (async () => {
                    function visible(el){
                        const style = getComputedStyle(el);
                        if (style.visibility === 'hidden' || style.display === 'none') return false;
                        const r = el.getBoundingClientRect();
                        return r.width > 0 && r.height > 0;
                    }
                    function collect(doc, frameOffsetX, frameOffsetY){
                        const selectors = 'a[href],area[href],button,input,textarea,select,[role],h1,h2,h3,h4,h5,h6,p,[tabindex]';
                        const els = Array.from(doc.querySelectorAll(selectors));
                        const items = [];
                        for (let i = 0; i < els.length; i++){
                            const el = els[i];
                            const rect = el.getBoundingClientRect();
                            if (rect.width <= 0 || rect.height <= 0) continue;
                            if (!visible(el)) continue;
                            const ariaLabel = el.getAttribute('aria-label');
                            const ariaLabelled = el.getAttribute('aria-labelledby');
                            let name = '';
                            if (ariaLabel) name = ariaLabel;
                            else if (ariaLabelled) {
                                const id = ariaLabelled;
                                const ref = doc.getElementById(id);
                                if (ref) name = ref.innerText || '';
                            }
                            if (!name) name = (el.getAttribute('alt') || el.innerText || '').trim();
                            const role = el.getAttribute('role') || el.tagName.toLowerCase();
                            items.push({
                                role,
                                name,
                                rect: {
                                    x: rect.left + (doc.defaultView?.scrollX||0) + frameOffsetX,
                                    y: rect.top + (doc.defaultView?.scrollY||0) + frameOffsetY,
                                    width: rect.width,
                                    height: rect.height
                                },
                                tabindex: el.tabIndex
                            });
                        }
                        return items;
                    }

                    async function walk(win, ox, oy){
                        let all = collect(win.document, ox, oy);
                        const frames = Array.from(win.document.querySelectorAll('iframe'));
                        for (const f of frames){
                            try{
                                const r = f.getBoundingClientRect();
                                const fx = r.left + (win.scrollX||0) + ox;
                                const fy = r.top + (win.scrollY||0) + oy;
                                const cw = f.contentWindow;
                                if (cw && cw.document) {
                                    all = all.concat(await walk(cw, fx, fy));
                                }
                            }catch(e){ /* cross-origin or access denied */ }
                        }
                        return all;
                    }

                    try {
                        return await walk(window, 0, 0);
                    } catch(e) {
                        return [];
                    }
        })();
        """

        try:
            dom_items = page.evaluate(js)
        except Exception:
            dom_items = []

        # Site metadata
        try:
            page_title = page.title()
        except Exception:
            page_title = ""
        parsed = urlparse(url)
        site_name = page_title.strip() or (parsed.netloc or parsed.path or url).strip()

        browser.close()

    # Build filtered accessibility list as before
    acc_items: List[Dict[str, Any]] = []
    if accessibility:
        flatten_accessibility_tree(accessibility, acc_items)

    result = {
        "items": dom_items,
        "accessibility": acc_items,
        "screenshot": screenshot_path,
        "imageSize": {"width": page_width, "height": page_height},
    }
    # Optional: write an HTML report combining both views
    try:
        # Compute relative image path from report location
        report_dir = os.path.dirname(os.path.abspath(output_html)) or os.getcwd()
        screenshot_src: Optional[str] = None
        if screenshot_path and os.path.exists(screenshot_path):
            try:
                screenshot_src = os.path.relpath(os.path.abspath(screenshot_path), start=report_dir)
            except Exception:
                screenshot_src = screenshot_path

        html_report = generate_html_report(
            dom_items=dom_items,
            site_name=site_name,
            url=url,
            screenshot_src=screenshot_src,
            image_size={"width": page_width, "height": page_height} if (page_width and page_height) else None,
        )
        with open(output_html, "w", encoding="utf-8") as f:
            f.write(html_report)
    except Exception:
        pass

    # Write a JSON sidecar next to the screenshot so GUI can annotate locations
    try:
        json_path = os.path.splitext(screenshot_path)[0] + ".json"
        with open(json_path, "w", encoding="utf-8") as jf:
            json.dump({
                "dom_items": dom_items,
                "accessibility": acc_items,
                "imageSize": {"width": page_width, "height": page_height},
                "url": url,
                "siteName": site_name,
            }, jf, indent=2)
    except Exception:
        json_path = None

    result["json"] = json_path
    return result


def generate_html_report(dom_items: List[Dict[str, Any]], site_name: str, url: str, screenshot_src: Optional[str], image_size: Optional[Dict[str, int]] = None) -> str:
    # Numbered list matching UI order (1, 2, 3...)
    rows = []
    for i, it in enumerate(dom_items, start=1):
        role = html.escape(str(it.get("role", "")))
        name = html.escape(str(it.get("name", "")))
        rows.append(f"<li><strong>{i}.</strong> <em>{role}</em> - {name}</li>")

    safe_site = html.escape(site_name or url)
    safe_url = html.escape(url)
    alt_text = html.escape(f"screenshot of {site_name or url} and the visual representation of its reading order")

    image_block = ""
    if screenshot_src:
        overlay = ""
        if image_size and image_size.get("width") and image_size.get("height"):
            iw = image_size["width"]
            ih = image_size["height"]
            pins = []
            for i, it in enumerate(dom_items, start=1):
                rect = it.get("rect", {}) or {}
                x = float(rect.get("x", 0))
                y = float(rect.get("y", 0))
                # position marker near top-left of rect
                left_pct = (x / iw) * 100 if iw else 0
                top_pct = (y / ih) * 100 if ih else 0
                pins.append(f"<div class='pin' style='left:{left_pct:.4f}%;top:{top_pct:.4f}%;'><span>{i}</span></div>")
            overlay = "\\n".join(pins)
        image_block = f"""
  <figure>
    <div class="shot">
      <img src="{html.escape(screenshot_src)}" alt="{alt_text}" />
      <div class="overlay">{overlay}</div>
    </div>
    <figcaption class="meta">Visual reading order (numbers on screenshot match the list below).</figcaption>
  </figure>
"""

    html_doc = f"""<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width,initial-scale=1" />
  <title>{safe_site} - Reading Order</title>
  <style>
    body {{ font-family: system-ui, -apple-system, Segoe UI, Roboto, Arial, sans-serif; padding: 24px; }}
    li {{ margin: 8px 0; }}
    .meta {{ color: #666; font-size: 0.9em; }}
    figure {{ margin: 16px 0; }}
    .shot {{ position: relative; display: inline-block; max-width: 100%; }}
    .shot > img {{ max-width: 100%; height: auto; border: 1px solid #ddd; display: block; }}
    .overlay {{ position: absolute; inset: 0; pointer-events: none; }}
    .pin {{ position: absolute; transform: translate(-40%, -40%); }}
    .pin > span {{ display: inline-block; background: rgba(0,120,215,0.9); color: #fff; border-radius: 999px; padding: 4px 8px; font: 600 14px/1.0 system-ui, -apple-system, Segoe UI, Roboto, Arial; border: 1px solid #fff; box-shadow: 0 1px 2px rgba(0,0,0,0.25); }}
  </style>
</head>
<body>
  <h1>{safe_site}</h1>
  <p class="meta">URL: <a href="{safe_url}">{safe_url}</a></p>
  {image_block}
  <h2>{safe_site} reading order list</h2>
  <ol>
    {''.join(rows)}
  </ol>
  <p class="meta">Generated by reading_order.py - a visual approximation of keyboard/tab reading order.</p>
</body>
</html>
"""
    return html_doc


def main(argv: List[str] | None = None) -> int:
    parser = argparse.ArgumentParser(description="Generate a reading-order report for a webpage")
    parser.add_argument("url", help="URL of the page to scan (include https://)")
    parser.add_argument("--output", "-o", default="reading_order_report.html", help="HTML output file")
    parser.add_argument("--headful", action="store_true", help="Run browser non-headless for debugging")
    args = parser.parse_args(argv)

    url = args.url
    out_file = args.output

    print(f"Loading page: {url}")

    try:
        result = scan_page(url, out_file, headful=args.headful)
    except Exception as e:
        print(f"Error scanning page: {e}")
        return 2

    # Console summary of DOM-collected items
    dom_items = result.get("items", [])
    acc_items = result.get("accessibility", [])
    print(f"Found {len(dom_items)} DOM items and {len(acc_items)} accessibility items - wrote {out_file}")
    for i, it in enumerate(dom_items, start=1):
        role = it.get("role")
        name = it.get("name")
        print(f"{i:3d}. [{role}] {name}")

    print("Done.")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())