mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/xray/policy.py

@@ -0,0 +1,305 @@
+"""What the X-ray crawler may tap. It fails closed: only a navigation-shaped control whose words name no act."""
+
+import re
+from dataclasses import dataclass
+
+from .. import harness_api
+from ..packs.core import ACT_LABEL, NEVER
+from ..secret_filter import redact
+
+# Words a crawler never taps, on top of the engine's commit words, wherever they sit in a label. Whole words, case
+# folded.
+# Screen text is data: a label is matched against these lists and never adds to them.
+DENY = re.compile(
+    r"\b(delete|erase|reset|wipe|remove|sign ?out|log ?out|sign ?off|deactivate|disable account|"
+    r"buy|purchase|subscribe|subscription|trial|try (?:it )?free|"
+    r"upgrade|go premium|get premium|get pro|unlock|pay|checkout|check out|order|book|donate|tip|"
+    r"call|dial|facetime|message|send|post|share|invite|publish|upload|reply|comment|"
+    r"allow|don'?t allow|accept|agree|decline|approve|confirm|submit|verify|authenticate|"
+    r"sign ?in|log ?in|sign ?up|register|create (?:an )?account|"
+    r"block|mute|unfollow|follow|unmatch|cancel subscription|install|download|"
+    r"turn (?:on|off)|enable|disable|disconnect|pair|forget|"
+    r"emergency|sos|power off|shut ?down|restart|redeem|claim|activate)\b", re.I)
+# Act verbs common on screens as nouns ("Feels like 67°", "Clear"): they count only as a label's first word.
+LEADING_ONLY = ("like", "likes", "liked", "react", "get", "request", "cancel", "clear", "next", "update", "report",
+                "done", "continue", "start", "begin", "restore", "apply", "join", "connect", "save", "open in", "go")
+_LEADING_ONLY = re.compile(r"\b(" + "|".join(re.escape(word) for word in LEADING_ONLY) + r")\b", re.I)
+# A label that starts with any of these, or with a word above, reads as a command: never tapped, whatever follows.
+LEADING = re.compile(r"^(?:" + "|".join(re.escape(word) for word in LEADING_ONLY) + r"|add|new|create|edit|compose|"
+                     r"write|record|scan|play|shuffle|try|rate|leave|end|archive|hide|pin|unpin|mark|empty|free up|"
+                     r"offload|translate|retry|skip|ok|okay|yes|no|tap|swipe|press|click|accept|send)\b", re.I)
+BUTTON_VERB = re.compile(r"^(edit|add|new|create|open|get|go|try|start|join|sign in|log in|sign up|learn more|"
+                         r"skip|close|ok|yes|no|retry|refresh|search|filter|sort|select|view|show|hide|play|"
+                         r"pause|stop|record|scan)\b", re.I)
+SEE_ALL = re.compile(r"^(see all|show all|view all|more|show more|see more|all)\b", re.I)
+# A developer's identifier standing in for a label: where it leads is unknown.
+IDENTIFIER = re.compile(r"^(?=.*[_.]|[a-z0-9]+(?:-[a-z0-9]+){2,}$)[A-Za-z0-9_.\-]+$")
+# Roles never tapped.
+CONTROL_ROLES = frozenset({"Switch", "Toggle", "Slider", "Stepper", "Picker", "PickerWheel", "DatePicker",
+                           "SegmentedControl", "TextField", "SecureTextField", "SearchField", "TextView", "Key",
+                           "Keyboard", "Menu", "MenuItem", "Alert", "Sheet", "Image", "Icon", "StatusBar",
+                           "NavigationBar", "Toolbar", "TabBar", "ProgressIndicator", "ActivityIndicator",
+                           "PageIndicator", "ScrollBar", "Map", "WebView"})
+TOGGLES = frozenset({"Switch", "Toggle"})
+CHROME_ROLES = frozenset({"Toolbar", "TabBar", "SearchField", "Keyboard"})
+CHEVRON = re.compile(r"^(chevron\.(forward|right)|disclosure|›|>)$", re.I)
+# A row's own info button ("More Info", the circled i): the button opens the details, and the row itself may act
+# (a Wi-Fi network joins, a Bluetooth device connects). Such a row is never tapped.
+INFO = re.compile(r"^(more info|info|info\.circle|i)$", re.I)
+CARD_MIN_H, CARD_MIN_W = .1, .3
+DATA_ROW_MIN_W, DATA_ROW_PARTS = .7, 3
+ICON_WORDS = frozenset({"heart", "star", "bookmark", "plus", "minus", "ellipsis", "more", "menu", "close", "xmark",
+                        "trash", "camera", "mic", "microphone", "play", "pause", "share", "cart", "bag", "bell",
+                        "search", "filter", "gift", "favorite", "favourite", "settings", "gear", "info"})
+# A row outside the content area (under the bars) is reached by scrolling, not tapped where it sits.
+CONTENT_TOP, CONTENT_BOTTOM = .12, .88
+TAB_BAR_TOP = .88
+OCR_ROW_LEFT_MAX = .4
+OCR_ROW_MAX_WORDS = 5
+OCR_ALIGN = .03
+OCR_CENTRED = .1
+
+
+@dataclass(frozen=True)
+class Verdict:
+    ok: bool
+    reason: str   # why: "cell", "chevron row", "tab", "link", "see all", "list row" when ok; the refusal otherwise
+
+
+def image_only(snapshot):
+    # Unsure is image-only, where stricter rules apply: it fails closed.
+    if getattr(snapshot, "source", "") in ("mirroring", "screen", "ocr"):
+        return True
+    roles = {element.role for element in snapshot.elements}
+    return not roles - {"StaticText", "SearchField", "TextField"}
+
+
+def plain(text):
+    """A label on one line, masked here at the source (secret_filter), so no map, event or report holds a secret."""
+    return redact(" ".join(str(text or "").replace("\u00a0", " ").split()))
+
+
+def _first_word_only(text):
+    """``text`` with the LEADING_ONLY words after its first word taken out: what the act lists read."""
+    first, _, rest = text.partition(" ")
+    return " ".join((first + " " + _LEADING_ONLY.sub(" ", rest)).split())
+
+
+def act_words(label):
+    text = plain(label)
+    if not text:
+        return ""
+    lead = LEADING.match(text)
+    if lead:
+        return f"never tapped: “{lead.group(0).lower()}”"
+    read = _first_word_only(text)
+    act = harness_api.commit_act("TAP", read, None, None)
+    if act:
+        return f"names an act ({act})"
+    if ACT_LABEL.match(text) or NEVER.search(read):
+        return "names an act"
+    # An identifier's words count too: "AUTH_PROX_SIGN_IN_CELL" says "sign in".
+    spaced = re.sub(r"[_\-.]+", " ", text)
+    spaced_read = _first_word_only(spaced)
+    found = (DENY.search(read) or DENY.search(spaced_read) or LEADING.match(spaced)
+             or (NEVER.search(spaced_read) if spaced != text else None))
+    if found:
+        return f"never tapped: “{found.group(0).lower()}”"
+    return ""
+
+
+def _inside(point, rect, pad=0.0):
+    x, y = point
+    rx, ry, rw, rh = rect
+    return rx - pad <= x <= rx + rw + pad and ry - pad <= y <= ry + rh + pad
+
+
+def _contains(outer, inner):
+    return (outer[0] - .005 <= inner[0] and outer[1] - .005 <= inner[1]
+            and inner[0] + inner[2] <= outer[0] + outer[2] + .005 and inner[1] + inner[3] <= outer[1] + outer[3] + .005)
+
+
+def in_tab_bar(element, snapshot):
+    if "XCUIElementTypeTabBar" in (element.locator or ""):
+        return True
+    bars = [e for e in snapshot.elements if e.role == "TabBar"]
+    return any(_inside(element.center, bar.rect) for bar in bars)
+
+
+def holds_toggle(element, snapshot):
+    """A cell or row with a switch inside it: tapping it could flip the switch."""
+    for other in snapshot.elements:
+        if other is element or other.role not in TOGGLES:
+            continue
+        if _inside(other.center, element.rect) or (element.locator and other.locator.startswith(element.locator + "/")):
+            return True
+    return False
+
+
+def has_chevron(element, snapshot):
+    """A row with a disclosure chevron: an image named like one inside it (Settings' rows: chevron.forward)."""
+    for other in snapshot.elements:
+        if other is element or not CHEVRON.match(plain(other.label)):
+            continue
+        if (element.locator and other.locator.startswith(element.locator + "/")) or _inside(other.center, element.rect):
+            return True
+    return False
+
+
+def holds_info(element, snapshot):
+    """A row with an info button inside it (Settings' Wi-Fi networks and Bluetooth devices)."""
+    for other in snapshot.elements:
+        if other is element or other.role not in ("Button", "Image") or not INFO.match(plain(other.label)):
+            continue
+        if (element.locator and other.locator.startswith(element.locator + "/")) or _inside(other.center, element.rect):
+            return True
+    return False
+
+
+CHECKMARK = re.compile(r"^(selected|checkmark|checked|checkmark\.circle(\.fill)?)$", re.I)
+
+
+def choice_list(snapshot):
+    # A tap on a row of a list of options picks one, which changes a setting. A selected tab or segment is not one.
+    for element in snapshot.elements:
+        if in_tab_bar(element, snapshot) or "SegmentedControl" in (element.locator or ""):
+            continue
+        if element.selected and element.role == "Cell":
+            return True
+        if element.role in ("Image", "Button") and CHECKMARK.match(plain(element.label)):
+            return True
+    return False
+
+
+def under_chrome(element, snapshot):
+    """Whether the tap would land on a toolbar, a search bar or the keyboard drawn over the content."""
+    point = element.tap_point
+    for other in snapshot.elements:
+        if other is element or other.role not in CHROME_ROLES:
+            continue
+        if _inside(point, other.rect):
+            return True
+    return False
+
+
+def decide(element, snapshot):
+    """Whether the crawler may tap ``element`` on ``snapshot``, and why."""
+    label = plain(element.label)
+    words = act_words(label) or act_words(element.value if element.role not in TOGGLES else "")
+    if words:
+        return Verdict(False, words)
+    if element.role in TOGGLES or element.role in CONTROL_ROLES:
+        return Verdict(False, "a control, not navigation" if element.role not in TOGGLES else "a switch")
+    if element.editable:
+        return Verdict(False, "a text field")
+    if not element.enabled or "TAP" not in element.actions:
+        return Verdict(False, "not tappable")
+    if not label:
+        return Verdict(False, "no label")
+    if holds_toggle(element, snapshot):
+        return Verdict(False, "holds a switch")
+    if image_only(snapshot):
+        return _decide_ocr(element, snapshot, label)
+    if IDENTIFIER.match(label):
+        return Verdict(False, "no readable label")
+    x, y = element.tap_point
+    tab = in_tab_bar(element, snapshot)
+    if not tab and not CONTENT_TOP <= y <= CONTENT_BOTTOM:
+        return Verdict(False, "outside the content area")
+    if not tab and under_chrome(element, snapshot):
+        return Verdict(False, "under a bar")
+    if tab and element.role == "Button":
+        return Verdict(True, "tab")
+    if choice_list(snapshot) and not has_chevron(element, snapshot) and element.role != "Link":
+        return Verdict(False, "an option in a choice list")
+    if holds_info(element, snapshot):
+        return Verdict(False, "a row with its own info button: the row itself may join or connect")
+    if element.role == "Cell":
+        return Verdict(True, "cell")
+    if element.role == "Link":
+        return Verdict(True, "link")
+    if element.role == "Button" and has_chevron(element, snapshot):
+        return Verdict(True, "chevron row")
+    if element.role == "Button" and "XCUIElementTypeCell[" in (element.locator or ""):
+        return Verdict(True, "cell")
+    if element.role in ("Button", "StaticText") and SEE_ALL.match(label):
+        return Verdict(True, "see all")
+    if element.role in ("Button", "Other") and card_shaped(element, label):
+        return Verdict(True, "card")
+    return Verdict(False, "not navigation-shaped")
+
+
+def card_shaped(element, label):
+    """A card (tall) or a full-width row of data whose label isn't one icon's word: Weather's modules and days."""
+    x, y, w, h = element.rect
+    if label.casefold() in ICON_WORDS or len(re.findall(r"[A-Za-z]{2,}", label)) == 0:
+        return False
+    if " " not in label and re.search(r"[a-z][A-Z]", label):
+        return False  # one token with capitals inside it ("KxLxpHjhdScjmXV"): an id, not words
+    if h >= CARD_MIN_H and w >= CARD_MIN_W:
+        return True
+    return w >= DATA_ROW_MIN_W and len([part for part in label.split(",") if part.strip()]) >= DATA_ROW_PARTS
+
+
+def _decide_ocr(element, snapshot, label):
+    """Image-only: a list row or a tab label, from where the line sits and what sits beside it."""
+    x, y, w, h = element.rect
+    cx, cy = element.center
+    words = label.split()
+    if any(ch.isdigit() for ch in label) and not re.search(r"[A-Za-z]{3}", label):
+        return Verdict(False, "a number")
+    if re.fullmatch(r"[A-Z0-9 &'’.,-]{2,}", label) and len(label) > 3:
+        return Verdict(False, "a heading")
+    if BUTTON_VERB.match(label) and len(words) <= 3:
+        return Verdict(False, "reads like a button")
+    if label.endswith((".", "!", "?", ":")) or len(words) > OCR_ROW_MAX_WORDS:
+        return Verdict(False, "a sentence")
+    lines = [e for e in snapshot.elements if e is not element and e.label]
+    if cy >= TAB_BAR_TOP:
+        row = [e for e in lines if abs(e.center[1] - cy) < .015 and len(plain(e.label).split()) <= 2]
+        if len(row) >= 2 and len(words) <= 2:
+            return Verdict(True, "tab")
+        return Verdict(False, "outside the content area")
+    if not CONTENT_TOP <= cy <= CONTENT_BOTTOM:
+        return Verdict(False, "outside the content area")
+    if abs(cx - .5) < OCR_CENTRED and x > .15:
+        return Verdict(False, "centred, reads like a button")
+    if SEE_ALL.match(label):
+        return Verdict(True, "see all")
+    if x > OCR_ROW_LEFT_MAX:
+        return Verdict(False, "not a list row")
+    aligned = [e for e in lines if abs(e.rect[0] - x) < OCR_ALIGN and e.center[1] != cy
+               and abs(e.center[1] - cy) < .12 and len(plain(e.label).split()) <= OCR_ROW_MAX_WORDS]
+    if not aligned:
+        return Verdict(False, "not a list row")
+    return Verdict(True, "list row")
+
+
+SAFE_DISMISS = re.compile(r"^(not now|cancel|close)$", re.I)
+
+
+def safe_dismiss(buttons):
+    """The one dialog button the crawler may press to get it out of the way, or None: "Not Now", "Cancel" or "Close"."""
+    # Anything else (Allow, Don't Allow, OK, Continue) is the user's to answer.
+    for name in buttons or ():
+        if SAFE_DISMISS.match(plain(name)):
+            return name
+    return None
+
+
+# Apps where a tap on a plain row acts in a way words and shapes can't show: App X-ray doesn't start in them.
+ACTING_APPS = {
+    "com.apple.mobilephone": ("Phone", "a tap on a row there places a call"),
+    "com.apple.facetime": ("FaceTime", "a tap on a row there places a call"),
+    "com.apple.shortcuts": ("Shortcuts", "a tap on a tile there runs a shortcut"),
+    "com.apple.Home": ("Home", "a tap on a tile there switches an accessory"),
+}
+
+
+def app_refusal(bundle):
+    """One sentence for an app X-ray won't map (what happened, then what to do), or None for any other app."""
+    found = ACTING_APPS.get(bundle if isinstance(bundle, str) else "")
+    if found is None:
+        return None
+    name, why = found
+    return f"App X-ray doesn't map {name}: {why}. Pick another app."

mobile_agent/xray/register.py

@@ -0,0 +1,43 @@
+from ..api_errors import APIError
+from ..api_routes import Response, Route
+from ..api_routes import register as add_route
+from . import job, policy
+
+HOOK_ORDER = 1       # before memory routines (10): an x-ray run is never a routine
+
+
+def start(request):
+    """POST /api/xray/app: {"appId": bundle, "device"?, "screens"?, "minutes"?, "key"?} -> 201 {"runId"}."""
+    # A task like any other: Runtime.create asks the plan gate, the phone's owner and the queue.
+    body = request.body if isinstance(request.body, dict) else {}
+    if set(body) - {"appId", "device", "screens", "minutes", "key"}:
+        raise ValueError("App X-ray takes appId, device, screens, minutes and key")
+    bundle = body.get("appId")
+    if not isinstance(bundle, str) or not 1 <= len(bundle) <= 160:
+        raise ValueError("appId is the app's bundle ID")
+    key, device = body.get("key"), body.get("device")
+    if key is not None and (not isinstance(key, str) or not 1 <= len(key) <= 100):
+        raise ValueError("key is 1 to 100 characters")
+    if device is not None and not isinstance(device, str):
+        raise ValueError("device must be a device's id, UDID or name")
+    refusal = policy.app_refusal(bundle)
+    if refusal:
+        raise APIError(refusal, 422, "xray_app_refused")
+    options = job.clean({name: body[name] for name in ("screens", "minutes") if name in body})
+    runtime = request.runtime
+    app = job.find_app(runtime, bundle, device)
+    if app is None:
+        raise ValueError("Choose an app that is installed on the phone")
+    origin = request.origin if request.origin in ("app", "tui", "cli") else "api"
+    created = runtime.create(app["id"], job.GOAL.format(name=app["name"]), "live", f"xray-{key}" if key else None,
+                             **({"device": device} if device is not None
+                                else {}), extras={"xray": options}, origin=origin, queue=True)
+    run, _ = created if key else (created, False)
+    return Response.json({"runId": run.id}, 201)
+
+
+def register(api):
+    """``api`` is mobile_agent.harness_api."""
+    api.register_run_field("xray", lambda value, runtime: job.clean(value), model=False)  # it maps with no model
+    api.register_pre_run(job.hook, order=HOOK_ORDER)
+    add_route(Route("xray", "POST", "/api/xray/app", start))

mobile_agent/xray/report.py

@@ -0,0 +1,283 @@
+"""An X-ray map as one self-contained page (report.html): it makes no requests, and every screen string is escaped."""
+
+import base64
+from pathlib import Path
+
+from .. import links
+from ..verify.report import BASE_STYLE, CSP, _e, brand, icon
+
+XRAY_STYLE = """
+.tag.tone::before { background: var(--violet); }
+.facts-card { margin-top: 32px; }
+.grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(132px, 1fr)); gap: 20px 16px; }
+.tile { min-width: 0; scroll-margin-top: 24px; }
+.tile:target .thumb-x { box-shadow: 0 0 0 2px var(--violet); }
+.thumb-x { display: block; aspect-ratio: 402 / 874; border-radius: 18px; overflow: hidden; background: var(--sunken);
+  box-shadow: var(--shadow-thumb); }
+.thumb-x img, .thumb-x svg { display: block; width: 100%; height: 100%; object-fit: cover; object-position: top; }
+.tile h3 { margin: 10px 0 0; font-size: 14px; line-height: 20px; font-weight: var(--weight-medium);
+  overflow-wrap: anywhere; }
+.tile .via { margin: 2px 0 0; font-size: 12px; line-height: 18px; color: var(--ink-3); overflow-wrap: anywhere; }
+.tile .opens { margin: 4px 0 0; font-size: 12px; line-height: 18px; color: var(--ink-2); }
+.tile .pw { color: var(--amber); font-weight: var(--weight-medium); }
+.depth + .depth { margin-top: 32px; }
+.depth h3.level { margin: 0 0 12px; font-size: 13px; line-height: 20px; font-weight: var(--weight-medium);
+  color: var(--ink-3); }
+.wf-row { fill: color-mix(in srgb, var(--ink) 6%, transparent); }
+.wf-bar { fill: color-mix(in srgb, var(--ink) 9%, transparent); }
+.wf-text { fill: color-mix(in srgb, var(--ink) 22%, transparent); }
+.wf-control { fill: color-mix(in srgb, var(--violet) 35%, transparent); }
+.paywall { display: grid; grid-template-columns: 132px minmax(0, 1fr); gap: 20px; padding: 20px; }
+.paywall + .paywall { border-top: 1px solid var(--line); }
+.paywall h3 { margin: 0; font-size: 16px; line-height: 24px; font-weight: var(--weight-title); }
+.paywall .headline { margin: 2px 0 0; color: var(--ink-2); overflow-wrap: anywhere; }
+table.plans { width: 100%; margin-top: 12px; border-collapse: collapse; font-size: 13px; line-height: 20px;
+  font-variant-numeric: tabular-nums; }
+table.plans th { text-align: left; font-weight: var(--weight-medium); color: var(--ink-3); padding: 6px 12px 6px 0;
+  border-bottom: 1px solid var(--line); }
+table.plans td { padding: 8px 12px 8px 0; border-bottom: 1px solid var(--line); overflow-wrap: anywhere; }
+table.plans tr:last-child td { border-bottom: 0; }
+.signals { margin: 10px 0 0; font-size: 12px; line-height: 18px; color: var(--ink-3); }
+ul.tree, ul.tree ul { list-style: none; margin: 0; padding: 0; }
+ul.tree { padding: 16px 20px; font-size: 13px; line-height: 22px; }
+ul.tree ul { padding-left: 18px; border-left: 1px solid var(--line); margin-left: 6px; }
+ul.tree a { text-decoration: none; }
+ul.tree a:hover { text-decoration: underline; }
+ul.tree .edge { color: var(--ink-3); }
+ul.tree .again { color: var(--ink-3); }
+table.left { width: 100%; border-collapse: collapse; font-size: 13px; line-height: 20px; }
+table.left td, table.left th { text-align: left; padding: 10px 16px; border-bottom: 1px solid var(--line);
+  vertical-align: top; overflow-wrap: anywhere; }
+table.left th { font-weight: var(--weight-medium); color: var(--ink-3); }
+table.left tr:last-child td { border-bottom: 0; }
+table.left td.n { font-variant-numeric: tabular-nums; color: var(--ink-2); white-space: nowrap; }
+.why { margin: 0 0 12px; color: var(--ink-2); max-width: 720px; }
+@media (max-width: 640px) {
+  .grid { grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 16px 12px; }
+  .paywall { grid-template-columns: 96px minmax(0, 1fr); padding: 16px; gap: 16px; }
+}
+"""
+STYLE = BASE_STYLE + XRAY_STYLE
+APP_NAMES = {"com.apple.Preferences": "Settings", "com.apple.weather": "Weather", "com.apple.mobilesafari": "Safari",
+             "com.apple.Maps": "Maps", "com.apple.MobileSMS": "Messages", "com.apple.mobilenotes": "Notes"}
+PERIODS = {"week": "Weekly", "month": "Monthly", "quarter": "Quarterly", "half-year": "Every 6 months",
+           "year": "Yearly", "lifetime": "Lifetime", "": "Not stated"}
+
+
+def duration(seconds):
+    seconds = float(seconds or 0)
+    if seconds < 60:
+        return f"{round(seconds)} s"
+    minutes, rest = divmod(round(seconds), 60)
+    return f"{minutes} min {rest:02d} s"
+
+
+def app_name(result):
+    bundle = (result.get("app") or {}).get("bundle", "")
+    if bundle in APP_NAMES:
+        return APP_NAMES[bundle]
+    screens = result.get("screens") or []
+    return (screens[0].get("title") if screens else "") or bundle or "App"
+
+
+def _thumb_src(base, screen):
+    name = screen.get("thumb")
+    if not name:
+        return None
+    try:
+        data = (Path(base) / name).read_bytes()
+    except OSError:
+        return None
+    return "data:image/jpeg;base64," + base64.b64encode(data).decode()
+
+
+def wireframe(screen):
+    """The screen's layout as a drawn skeleton: rows, bars, controls and text as bars of their own width."""
+    parts = ['<svg viewBox="0 0 100 217" preserveAspectRatio="none" aria-hidden="true">']
+    for box in screen.get("boxes") or ():
+        x, y, w, h, kind = box[0] * 100, box[1] * 217, box[2] * 100, box[3] * 217, box[4]
+        if kind == "row":
+            parts.append(f'<rect class="wf-row" x="{x:.1f}" y="{y:.1f}" width="{w:.1f}" height="{max(h - .6, .6):.1f}" '
+                         'rx="1.5"/>')
+        elif kind == "bar":
+            parts.append(f'<rect class="wf-bar" x="{x:.1f}" y="{y:.1f}" width="{w:.1f}" height="{h:.1f}"/>')
+        else:
+            line = min(h, 3.2)
+            cls = "wf-control" if kind == "control" else "wf-text"
+            parts.append(f'<rect class="{cls}" x="{x:.1f}" y="{y + (h - line) / 2:.1f}" width="{max(w, 2):.1f}" '
+                         f'height="{line:.1f}" rx="{line / 2:.1f}"/>')
+    parts.append("</svg>")
+    return "".join(parts)
+
+
+def _thumb(base, screen, alt):
+    src = _thumb_src(base, screen)
+    inner = (f'<img src="{src}" alt="{_e(alt)}" loading="lazy">' if src else wireframe(screen))
+    return f'<span class="thumb-x">{inner}</span>'
+
+
+def _plans(paywall):
+    rows = []
+    for plan in paywall.get("plans") or ():
+        per_month = (f"{plan.get('currency', '')} {plan['per_month']:.2f}" if plan.get("per_month")
+                     and plan.get("period") not in ("month", "lifetime") else "")
+        rows.append(f"<tr><td>{_e(plan.get('name') or PERIODS.get(plan.get('period', ''), ''))}</td>"
+                    f"<td>{_e(plan.get('price'))}</td><td>{_e(PERIODS.get(plan.get('period', ''), plan.get('period')))}"
+                    f"</td><td>{_e(per_month)}</td><td>{_e(plan.get('trial') or paywall.get('trial') or '')}</td></tr>")
+    if not rows:
+        return '<p class="empty">No prices read on this screen.</p>'
+    return ('<table class="plans"><thead><tr><th>Plan</th><th>Price</th><th>Billed</th><th>A month</th>'
+            '<th>Trial</th></tr></thead><tbody>' + "".join(rows) + "</tbody></table>")
+
+
+def _crumbs(screen):
+    return " › ".join(step.get("label", "") for step in screen.get("path") or ()) or "First screen"
+
+
+def render(result, base="."):
+    screens = result.get("screens") or []
+    edges = result.get("edges") or []
+    stats = result.get("stats") or {}
+    by_id = {s["id"]: s for s in screens}
+    name = app_name(result)
+    bundle = (result.get("app") or {}).get("bundle", "")
+    out_edges = {}
+    for edge in edges:
+        out_edges.setdefault(edge["from"], []).append(edge)
+    connection = "Pixels (iPhone Mirroring)" if result.get("connection") == "pixels" else "Accessibility tree"
+    lede = (f"{stats.get('screens', 0)} screens and {stats.get('edges', 0)} links, {stats.get('max_depth', 0)} taps "
+            f"deep, mapped in {duration(stats.get('wall_seconds'))} with no model.")
+    parts = [
+        "<!doctype html>", '<html lang="en"><head><meta charset="utf-8">',
+        f'<meta http-equiv="Content-Security-Policy" content="{CSP}">',
+        '<meta name="viewport" content="width=device-width, initial-scale=1">',
+        '<meta name="color-scheme" content="light dark">',
+        f"<title>{_e(name)} X-ray</title>", f"<style>{STYLE}</style></head><body><main>",
+        brand("App X-ray", bundle),
+        '<header class="head"><div class="chips">',
+        f'<span class="tag tone">{_e(connection)}</span><span class="tag">{icon("coin")}$0 in model calls</span>',
+        f"</div><h1>{_e(name)}</h1>", f'<p class="lede">{_e(lede)}</p>',
+        '<ul class="meta">',
+        f'<li>{icon("app")}<span class="mono">{_e(bundle)}</span></li>',
+        f'<li>{icon("calendar")}{_e((result.get("created_at") or "")[:16].replace("T", " "))}</li>',
+        f'<li>{icon("clock")}Stopped: {_e(result.get("stopped"))}</li></ul></header>',
+    ]
+    facts = [("Screens", stats.get("screens")), ("Links", stats.get("edges")), ("Deepest", stats.get("max_depth")),
+             ("Time", duration(stats.get("wall_seconds"))), ("Screens a minute", stats.get("screens_per_minute")),
+             ("Taps", stats.get("taps")), ("Left alone", stats.get("refused")), ("Paywalls", stats.get("paywalls")),
+             ("Ends with nothing to open", stats.get("dead_ends")), ("Model cost", "$0")]
+    parts.append('<section class="facts-card"><dl class="facts card">' + "".join(
+        f"<div><dt>{_e(k)}</dt><dd>{_e(v)}</dd></div>" for k, v in facts) + "</dl></section>")
+
+    paywalled = [s for s in screens if s.get("paywall")]
+    if paywalled:
+        parts.append(f'<section><h2>Paywalls<span class="count">{len(paywalled)}</span></h2><div class="card">')
+        for screen in paywalled:
+            pw = screen["paywall"]
+            parts.append('<div class="paywall"><a '
+                         f'href="#{_e(screen["id"])}">{_thumb(base, screen, screen.get("name") or screen["title"])}</a>'
+                         f'<div><h3>{_e(screen.get("name") or screen.get("title") or "Untitled")}</h3>'
+                         f'<p class="headline">{_e(pw.get("headline") or _crumbs(screen))}</p>{_plans(pw)}'
+                         f'<p class="signals">Read as a paywall from: {_e(", ".join(pw.get("signals") or ()))}. '
+                         f'{"Shows Restore Purchases. " if pw.get("restore") else ""}Nothing on it was tapped.</p>'
+                         "</div></div>")
+        parts.append("</div></section>")
+
+    parts.append(f'<section><h2>Screens<span class="count">{len(screens)}</span></h2>')
+    for heading, group in _branches(screens, by_id):
+        parts.append(f'<div class="depth"><h3 class="level">{_e(heading)} ({len(group)})</h3><div class="grid">')
+        for screen in group:
+            parts.append(_tile(base, screen, by_id, out_edges))
+        parts.append("</div></div>")
+    parts.append("</section>")
+
+    parts.append('<section><h2>Paths</h2><div class="card"><ul class="tree">'
+                 + _outline(screens, out_edges, by_id) + "</ul></div></section>")
+
+    refused = {}
+    for screen in screens:
+        for item in screen.get("refused") or ():
+            refused.setdefault(item["reason"], []).append(item["label"])
+    if refused:
+        parts.append(f'<section><h2>Left alone<span class="count">{stats.get("refused", 0)}</span></h2>'
+                     '<p class="why">The crawler taps only controls shaped like navigation whose words name no act. '
+                     'These it saw and didn’t tap.</p><div class="card"><table class="left"><thead><tr><th>Why</th>'
+                     '<th>Count</th><th>Examples</th></tr></thead><tbody>')
+        for reason, labels in sorted(refused.items(), key=lambda kv: -len(kv[1])):
+            examples = ", ".join(f"“{label}”" for label in list(dict.fromkeys(labels))[:6])
+            parts.append(f'<tr><td>{_e(reason)}</td><td class="n">{len(labels)}</td><td>{_e(examples)}</td></tr>')
+        parts.append("</tbody></table></div></section>")
+
+    parts.append(f'<footer class="foot"><span><a href="{links.MADE_WITH_XRAY}">Mobster</a> App X-ray, '
+                 'experimental.</span>'
+                 "<span>Screen text is shown as read from the app.</span></footer></main></body></html>")
+    return "".join(parts)
+
+
+def _branches(screens, by_id):
+    def top(screen):
+        seen = set()
+        while screen.get("depth", 0) > 1 and screen.get("parent") in by_id and screen["id"] not in seen:
+            seen.add(screen["id"])
+            screen = by_id[screen["parent"]]
+        return screen
+    opening = [s for s in screens if s.get("depth", 0) == 0]
+    groups = [("Where it opens", opening)] if opening else []
+    sections = {}
+    for screen in screens:
+        if screen.get("depth", 0) == 0:
+            continue
+        sections.setdefault(top(screen)["id"], []).append(screen)
+    for head_id, group in sections.items():
+        head = by_id.get(head_id, group[0])
+        groups.append((head.get("name") or head.get("title") or "Untitled", group))
+    return groups
+
+
+def _tile(base, screen, by_id, out_edges):
+    leads = out_edges.get(screen["id"], [])
+    opens = f"Opens {len(leads)}" if leads else "Nothing further"
+    parent = by_id.get(screen.get("parent"))
+    via = (f'From <a href="#{_e(parent["id"])}">{_e(parent.get("name") or parent.get("title") or parent["id"])}</a>'
+           f' by “{_e(screen.get("via"))}”' if parent else "Where the app opens")
+    flag = ' <span class="pw">Paywall</span>' if screen.get("paywall") else ""
+    return (f'<article class="tile" id="{_e(screen["id"])}">'
+            f'{_thumb(base, screen, screen.get("name") or screen.get("title"))}'
+            f'<h3>{_e(screen.get("name") or screen.get("title") or "Untitled")}{flag}</h3><p class="via">{via}</p>'
+            f'<p class="opens">{_e(opens)}</p></article>')
+
+
+def _outline(screens, out_edges, by_id):
+    """The crawl as nested lists: each screen under the one it was found from, each link with the control tapped."""
+    children = {}
+    for screen in screens:
+        children.setdefault(screen.get("parent") or "", []).append(screen)
+    lines = []
+
+    def walk(screen, depth):
+        lines.append('<li><a '
+                     f'href="#{_e(screen["id"])}">{_e(screen.get("name") or screen.get("title") or "Untitled")}</a>')
+        kids = children.get(screen["id"], [])
+        again = [e for e in out_edges.get(screen["id"], [])
+                 if e.get("to") and by_id.get(e["to"], {}).get("parent") != screen["id"]]
+        if kids or again:
+            lines.append("<ul>")
+            for kid in kids:
+                walk(kid, depth + 1)
+            for edge in again[:8]:
+                target = by_id.get(edge["to"], {})
+                lines.append(f'<li class="again">“{_e(edge["label"])}” goes back to <a href="#{_e(edge["to"])}">'
+                             f'{_e(target.get("name") or target.get("title") or edge["to"])}</a></li>')
+            lines.append("</ul>")
+        lines.append("</li>")
+
+    for root in children.get("", []):
+        walk(root, 0)
+    return "".join(lines)
+
+
+def write(result, folder, out=None):
+    folder = Path(folder)
+    path = Path(out) if out else folder / "report.html"
+    path.write_text(render(result, folder), encoding="utf-8")
+    return path