mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/xray/diff.py

@@ -0,0 +1,171 @@
+"""Two X-ray maps of one app compared: the screens added, removed and changed, and the paywalls' prices."""
+
+from .screens import jaccard, token
+
+MATCH = .5   # the least overlap of words for two screens with one title to be the same screen
+
+
+def _path(screen):
+    return tuple(step.get("key") or token(step.get("label", "")) for step in screen.get("path") or ())
+
+
+def _name(screen):
+    return screen.get("name") or screen.get("title") or screen.get("id") or "Untitled"
+
+
+def _where(screen):
+    labels = [step.get("label", "") for step in screen.get("path") or ()]
+    return " › ".join(labels) if labels else "the first screen"
+
+
+def match(before, after):
+    """{after id: before id} for the screens that are the same in both maps."""
+    pairs, used = {}, set()
+    by_path = {}
+    for screen in before:
+        by_path.setdefault(_path(screen), screen)
+    for screen in after:
+        old = by_path.get(_path(screen))
+        if old is not None and old["id"] not in used and (
+                token(_name(old)) == token(_name(screen))
+                or jaccard(old.get("tokens", ()), screen.get("tokens", ())) >= MATCH):
+            pairs[screen["id"]] = old["id"]
+            used.add(old["id"])
+    for screen in after:
+        if screen["id"] in pairs:
+            continue
+        best, score = None, MATCH
+        for old in before:
+            if old["id"] in used or token(old.get("title", "")) != token(screen.get("title", "")):
+                continue
+            overlap = jaccard(old.get("tokens", ()), screen.get("tokens", ()))
+            if overlap >= score:
+                best, score = old, overlap
+        if best is not None:
+            pairs[screen["id"]] = best["id"]
+            used.add(best["id"])
+    return pairs
+
+
+def _plan_key(plan):
+    return plan.get("period") or (plan.get("name") or "").casefold() or plan.get("line", "").casefold()
+
+
+def compare_paywalls(old, new):
+    """What changed between two paywalls: [{"kind", "plan", "before", "after"}]."""
+    changes = []
+    old_plans = {_plan_key(p): p for p in (old or {}).get("plans") or ()}
+    new_plans = {_plan_key(p): p for p in (new or {}).get("plans") or ()}
+    for key, plan in new_plans.items():
+        was = old_plans.get(key)
+        if was is None:
+            changes.append({"kind": "plan added", "plan": key, "before": None, "after": plan.get("price")})
+            continue
+        if (was.get("amount"), was.get("currency")) != (plan.get("amount"), plan.get("currency")):
+            changes.append({"kind": "price", "plan": key, "before": was.get("price"), "after": plan.get("price")})
+        if (was.get("trial") or "") != (plan.get("trial") or ""):
+            changes.append({"kind": "trial", "plan": key, "before": was.get("trial") or None,
+                            "after": plan.get("trial") or None})
+    for key, plan in old_plans.items():
+        if key not in new_plans:
+            changes.append({"kind": "plan removed", "plan": key, "before": plan.get("price"), "after": None})
+    if (old or {}).get("trial", "") != (new or {}).get("trial", ""):
+        changes.append({"kind": "trial", "plan": "", "before": (old or {}).get("trial") or None,
+                        "after": (new or {}).get("trial") or None})
+    return changes
+
+
+def compare(before, after):
+    old_screens = before.get("screens") or []
+    new_screens = after.get("screens") or []
+    pairs = match(old_screens, new_screens)
+    old_by_id = {s["id"]: s for s in old_screens}
+    new_by_id = {s["id"]: s for s in new_screens}
+    matched_old = set(pairs.values())
+    added = [s for s in new_screens if s["id"] not in pairs]
+    removed = [s for s in old_screens if s["id"] not in matched_old]
+    changed, paywalls = [], []
+    for new_id, old_id in pairs.items():
+        new, old = new_by_id[new_id], old_by_id[old_id]
+        gained = sorted(set(new.get("tokens", ())) - set(old.get("tokens", ())))
+        lost = sorted(set(old.get("tokens", ())) - set(new.get("tokens", ())))
+        if gained or lost:
+            changed.append({"before": old_id, "after": new_id, "name": _name(new), "where": _where(new),
+                            "added_words": gained[:20], "removed_words": lost[:20]})
+        if old.get("paywall") or new.get("paywall"):
+            moves = compare_paywalls(old.get("paywall"), new.get("paywall"))
+            if moves or bool(old.get("paywall")) != bool(new.get("paywall")):
+                paywalls.append({"screen": new_id, "name": _name(new), "where": _where(new),
+                                 "was_paywall": bool(old.get("paywall")), "is_paywall": bool(new.get("paywall")),
+                                 "changes": moves})
+    for screen in added:
+        if screen.get("paywall"):
+            paywalls.append({"screen": screen["id"], "name": _name(screen), "where": _where(screen),
+                             "was_paywall": False, "is_paywall": True, "new_screen": True,
+                             "changes": compare_paywalls(None, screen["paywall"])})
+    for screen in removed:
+        if screen.get("paywall"):
+            paywalls.append({"screen": screen["id"], "name": _name(screen), "where": _where(screen),
+                             "was_paywall": True, "is_paywall": False, "gone": True, "changes": []})
+    under = {}
+    for screen in added:
+        parent = new_by_id.get(screen.get("parent")) if screen.get("parent") else None
+        if parent is not None and parent["id"] in pairs:
+            under.setdefault(_name(parent), []).append(_name(screen))
+    return {"schema": "mobster.xray.diff/1", "app": (after.get("app") or before.get("app") or {}).get("bundle"),
+            "before": {"created_at": before.get("created_at"), "screens": len(old_screens)},
+            "after": {"created_at": after.get("created_at"), "screens": len(new_screens)},
+            "added": [{"id": s["id"], "name": _name(s), "where": _where(s)} for s in added],
+            "removed": [{"id": s["id"], "name": _name(s), "where": _where(s)} for s in removed],
+            "changed": changed, "paywalls": paywalls, "added_under": under}
+
+
+PERIOD_WORDS = {"week": "Weekly", "month": "Monthly", "quarter": "Quarterly", "half-year": "Six-month",
+                "year": "Yearly",
+                "lifetime": "Lifetime"}
+
+
+def summary(result):
+    """The comparison in plain sentences, most important first."""
+    lines = []
+    for item in result.get("paywalls") or ():
+        if item.get("new_screen"):
+            prices = ", ".join(c["after"] for c in item["changes"] if c.get("after"))
+            lines.append(f"New paywall screen: {item['name']} ({item['where']})" + (f", {prices}" if prices else ""))
+        elif item.get("gone"):
+            lines.append(f"Paywall gone: {item['name']} ({item['where']})")
+        elif item["is_paywall"] and not item["was_paywall"]:
+            lines.append(f"{item['name']} is a paywall now ({item['where']})")
+        for change in item.get("changes") or ():
+            if item.get("new_screen"):
+                continue
+            plan = PERIOD_WORDS.get(change["plan"], change["plan"].title() or "The")
+            if change["kind"] == "price":
+                lines.append(f"{plan} price went {change['before']} → {change['after']} on {item['name']}")
+            elif change["kind"] == "plan added":
+                lines.append(f"New {plan.lower()} plan at {change['after']} on {item['name']}")
+            elif change["kind"] == "plan removed":
+                lines.append(f"{plan} plan ({change['before']}) dropped from {item['name']}")
+            elif change["kind"] == "trial":
+                lines.append(f"Trial went {change['before'] or 'none'} → {change['after'] or 'none'} on {item['name']}")
+    for parent, names in (result.get("added_under") or {}).items():
+        count = len(names)
+        lines.append(f"{count} new screen{'s' if count != 1 else ''} under {parent}: {', '.join(names[:5])}")
+    listed = {n for names in (result.get("added_under") or {}).values() for n in names}
+    for item in result.get("added") or ():
+        if item["name"] not in listed:
+            lines.append(f"New screen: {item['name']} ({item['where']})")
+    for item in result.get("removed") or ():
+        lines.append(f"Gone: {item['name']} ({item['where']})")
+    for item in result.get("changed") or ():
+        bits = []
+        if item["added_words"]:
+            bits.append("now shows " + ", ".join(f"“{w}”" for w in item["added_words"][:4]))
+        if item["removed_words"]:
+            bits.append("no longer shows " + ", ".join(f"“{w}”" for w in item["removed_words"][:4]))
+        lines.append(f"{item['name']} changed: {'; '.join(bits)}")
+    if not lines:
+        lines.append("No changes: the same screens, words and prices.")
+    before, after = result.get("before") or {}, result.get("after") or {}
+    lines.append(f"Screens: {before.get('screens', 0)} before, {after.get('screens', 0)} after.")
+    return lines

mobile_agent/xray/diff_cli.py

@@ -0,0 +1,43 @@
+"""`mobster xray diff BEFORE AFTER`: what changed between two maps of one app."""
+
+import json
+import sys
+from pathlib import Path
+
+HELP = "compare two maps of one app"
+DESCRIPTION = (
+    "Compare two maps `mobster xray app` wrote: the screens added, removed and changed, and the paywall prices\n"
+               "that moved. Each argument is a map.json file or the folder that holds it. It reads two files on this\n"
+               "Mac and needs no phone and no plan.")
+EPILOG = ("exit codes: 0 compared (changes or none), 1 a map couldn't be read, 2 usage\n\n"
+          "examples:\n"
+          "  mobster xray diff before/map.json after/map.json\n"
+          "  mobster xray diff before after --json")
+
+
+def add_arguments(parser):
+    parser.add_argument("before", metavar="BEFORE", help="the older map: a map.json file or its folder")
+    parser.add_argument("after", metavar="AFTER", help="the newer map: a map.json file or its folder")
+    parser.add_argument("--json", action="store_true", help="print the comparison as JSON")
+
+
+def load(path):
+    path = Path(path).expanduser()
+    if path.is_dir():
+        path = path / "map.json"
+    return json.loads(path.read_text())
+
+
+def run(args):
+    from .diff import compare, summary
+    try:
+        result = compare(load(args.before), load(args.after))
+    except (OSError, ValueError, KeyError, TypeError) as error:
+        print(f"mobster xray: couldn't read a map ({type(error).__name__}). Pass map.json files or the folders that "
+              "hold them.", file=sys.stderr)
+        return 1
+    if args.json:
+        print(json.dumps(result, indent=1, ensure_ascii=False))
+    else:
+        print("\n".join(summary(result)))
+    return 0

mobile_agent/xray/job.py

@@ -0,0 +1,184 @@
+"""One App X-ray run: no model, only taps the policy allows; screen text is masked and never an instruction."""
+
+import json
+import os
+import re
+import time
+from pathlib import Path
+
+from .. import harness_api
+from .. import result_blocks as blocks
+from ..paths import user_data_dir
+from . import policy, report
+from .crawl import Caps, Crawler
+
+GOAL = "Map {name} with App X-ray"
+MAX_GALLERY = 60
+DEFAULT = {"screens": 30, "minutes": 5}
+LIMITS = {"screens": (1, 120), "minutes": (1, 30)}
+
+
+def clean(value):
+    """The run field ``xray``: ``{"screens": 1..120 (30), "minutes": 1..30 (5)}``. ValueError with a sentence."""
+    if value is True or value is None:
+        value = {}
+    if not isinstance(value, dict) or set(value) - set(LIMITS):
+        raise ValueError("xray is an object with screens (1 to 120) and minutes (1 to 30)")
+    out = dict(DEFAULT)
+    for name, (low, high) in LIMITS.items():
+        if name in value:
+            number = value[name]
+            if type(number) is not int or not low <= number <= high:
+                raise ValueError(f"xray.{name} is a whole number from {low} to {high}")
+            out[name] = number
+    return out
+
+
+def find_app(runtime, wanted, device=None):
+    phone = runtime.resolve_device(device) if getattr(runtime, "fleet", None) is not None else None
+    apps = [a for a in runtime.apps_for(phone) if a.get("bundleId") and a.get("installed") is not False]
+    wanted = wanted.strip()
+    return (next((a for a in apps if a["bundleId"] == wanted), None)
+            or next((a for a in apps if a.get("name", "").casefold() == wanted.casefold()), None))
+
+
+def folder_for(bundle, now=None):
+    """A new 0700 folder for this crawl under the data folder (the newest never replaces an older one)."""
+    safe = re.sub(r"[^A-Za-z0-9._-]", "_", bundle)[:128] or "app"
+    root = user_data_dir() / "xray"
+    folder = root / "apps" / safe / time.strftime("%Y%m%d-%H%M%S", time.localtime(now))
+    n = 1
+    while folder.exists():
+        n += 1
+        folder = folder.with_name(f"{folder.name}-{n}")
+    folder.mkdir(parents=True, mode=0o700)
+    for path in (folder, root):
+        os.chmod(path, 0o700)
+    return folder
+
+
+def shown_folder(folder):
+    """The folder as the result shows it: under the data folder, so a shared result names no account on this Mac."""
+    try:
+        return str(Path(folder).relative_to(user_data_dir()))
+    except ValueError:
+        return Path(folder).name
+
+
+def app_name(ctx, result):
+    try:
+        for app in ctx.runtime.apps():
+            if app.get("bundleId") == ctx.app_bundle and app.get("name"):
+                return app["name"]
+    except Exception:  # noqa: BLE001 -- the name is a nicety
+        pass
+    return report.app_name(result)
+
+
+def plural(count, word):
+    return f"{count} {word}{'' if count == 1 else 's'}"
+
+
+def answer_line(name, result):
+    stats = result["stats"]
+    line = (f"Mapped {plural(stats['screens'], 'screen')} of {name}, {plural(stats['max_depth'], 'tap')} deep, in "
+            f"{report.duration(stats['wall_seconds'])}, with no model.")
+    if stats["paywalls"]:
+        line += f" {plural(stats['paywalls'], 'paywall')}."
+    if stats["refused"]:
+        line += f" It left {plural(stats['refused'], 'control')} alone because they could act."
+    return line
+
+
+def result_blocks(result, folder):
+    """The gallery of screens, the paywall plans, and the stats, as validated result blocks."""
+    stats, out = result["stats"], []
+    items = [{"id": s["id"], "frameId": s["frame_id"], "caption": s["name"]}
+             for s in result["screens"] if s.get("frame_id")][:MAX_GALLERY]
+    if items:
+        out.append(blocks.gallery(items, title="Screens"))
+    rows = [(s["name"], plan) for s in result["screens"] if s.get("paywall") for plan in s["paywall"]["plans"]]
+    if rows:
+        currencies = {plan["currency"] for _, plan in rows}
+        money = len(currencies) == 1       # one currency: a money column; else the price as shown
+        price = ({"key": "price", "label": "Price", "type": "money", "currency": next(iter(currencies))} if money
+                 else {"key": "price", "label": "Price"})
+        out.append(blocks.table(
+            [{"key": "screen", "label": "Screen"}, {"key": "plan", "label": "Plan"}, price,
+             {"key": "period", "label": "Period"}, {"key": "trial", "label": "Trial"}],
+            [{"screen": name, "plan": plan["name"] or plan["period"] or plan["line"],
+              "price": plan["amount"] if money else plan["price"],
+              "period": report.PERIODS.get(plan["period"], plan["period"]), "trial": plan["trial"] or "None"}
+             for name, plan in rows], title="Paywall plans", id="plans"))
+    lines = [f"- Screens: {stats['screens']}, links: {stats['edges']}, taps: {stats['taps']}, scrolls: "
+             f"{stats['scrolls']}", f"- Time: {report.duration(stats['wall_seconds'])}",
+             f"- It stopped because it {result['stopped']}.",
+             f"- Left alone: {stats['refused']} controls that could act",
+             "- Model cost: $0", f"- Saved on this Mac in Mobster's data folder: {shown_folder(folder)}"]
+    out.append(blocks.markdown("\n".join(lines), title="How it went", id="stats"))
+    return blocks.envelope(out)
+
+
+def failure(reason, **fields):
+    return {"event": "result", "status": "error", "engine": "smart", "outcome": "couldnt_finish", "answer": None,
+            "reason": reason, "independently_verified": False, "proof": [], "actions": 0, "decisions": 0,
+            "costUsd": 0.0, "model": None, **fields}
+
+
+def run(ctx, driver):
+    """The result of the crawl for ``ctx`` (a run with the ``xray`` field): done, stopped, or why it could not map."""
+    options = ctx.extras["xray"]
+    bundle = ctx.app_bundle
+    refusal = policy.app_refusal(bundle) if bundle else None
+    if refusal or not bundle:
+        return failure(refusal or "App X-ray maps one app. Pick an app, then run it again.")
+    started = time.monotonic()
+    folder = folder_for(bundle)
+    log_file = folder / "crawl.log"
+
+    def log(message):
+        try:
+            with open(log_file, "a", encoding="utf-8") as handle:
+                handle.write(f"{time.monotonic() - started:7.1f}  {message}\n")
+        except OSError:
+            pass
+
+    crawler = Crawler(driver, bundle, caps=Caps(screens=options["screens"], seconds=options["minutes"] * 60.0),
+                      out_dir=folder, emit=ctx.emit, cancelled=ctx.cancelled, log=log)
+    broke = None
+    try:
+        result = crawler.run()
+    except Exception as error:  # noqa: BLE001 -- a lost phone or a driver fault: keep the map so far, retry nothing
+        broke = error
+        crawler.stopped = f"lost the phone ({type(error).__name__}); the last tap was not retried"
+        result = crawler.map()
+    (folder / "map.json").write_text(json.dumps(result, indent=1, ensure_ascii=False))
+    report.write(result, folder)
+    if not result["screens"]:
+        return failure(f"Mobster mapped no screens: it {result['stopped']}. Nothing was tapped.",
+                       xray={"folder": str(folder)})
+    stopped = ctx.cancelled()
+    from ..memory import writer
+    writer.from_xray(ctx.run_id, bundle, result)  # saved as facts when the run finishes
+    name = app_name(ctx, result)
+    # Every screen in the map is one of Mobster's own screenshots, so the result is proven, not a guess.
+    proof = [{"quote": f"Every screen in this map is a screenshot Mobster took in {name} on your iPhone.", "app": name}]
+    done = {"event": "result", "engine": "smart", "answer": answer_line(name, result),
+            "independently_verified": True, "proof": proof, "actions": result["stats"]["taps"], "decisions": 0,
+            "elapsed_ms": round((time.monotonic() - started) * 1000), "costUsd": 0.0, "model": None,
+            "blocks": result_blocks(result, folder),
+            "xray": {"folder": str(folder), "map": str(folder / "map.json"), "report": str(folder / "report.html")}}
+    if stopped:
+        return {**done, "status": "stopped", "outcome": "stopped", "reason": "Stopped by you. This is the map so far."}
+    if broke is not None:
+        return {**done, "status": "completion_not_confirmed", "outcome": "check", "actions_may_have_run": True,
+                "reason": f"Mobster lost the phone and stopped: {type(broke).__name__}. This is the map so far; "
+                          "the last tap was not repeated."}
+    return {**done, "status": "completed", "outcome": "done", "reason": None}
+
+
+def hook(ctx, driver, approve):
+    """Pre-run hook: a run with ``xray`` maps the app instead of calling a model."""
+    if (ctx.extras or {}).get("xray") is None or driver is None:
+        return None
+    return harness_api.PreRun(result=run(ctx, driver))

mobile_agent/xray/paywall.py

@@ -0,0 +1,188 @@
+"""A paywall and its plans, read from a screen's text. The crawler taps nothing on one, and nothing here acts on it."""
+
+import re
+from dataclasses import asdict, dataclass, field
+
+SYMBOLS = {"$": "USD", "US$": "USD", "£": "GBP", "€": "EUR", "¥": "JPY", "₹": "INR", "₩": "KRW", "A$": "AUD",
+           "C$": "CAD", "CA$": "CAD", "AU$": "AUD", "CHF": "CHF", "R$": "BRL", "kr": "SEK", "zł": "PLN", "₺": "TRY"}
+CODES = ("USD", "EUR", "GBP", "JPY", "CAD", "AUD", "CHF", "INR", "BRL", "SEK", "NOK", "DKK", "PLN", "KRW", "TRY")
+_SYMBOL = "|".join(re.escape(s) for s in sorted(SYMBOLS, key=len, reverse=True))
+_AMOUNT = r"\d{1,3}(?:[,.  ]\d{3})*(?:[.,]\d{1,2})?|\d+(?:[.,]\d{1,2})?"
+PRICE = re.compile(
+    rf"(?P<pre>{_SYMBOL}|\b(?:{'|'.join(CODES)})\b)\s?(?P<a1>{_AMOUNT})"
+    rf"|(?P<a2>{_AMOUNT})\s?(?P<post>{_SYMBOL}|\b(?:{'|'.join(CODES)})\b)")
+# A billing period, after a price or on its own ("/mo", "per week", "a year", "Annual", "Monthly").
+PERIODS = (
+    ("week", r"/\s?w(?:ee)?k\b|\bper week\b|\ba week\b|\bweekly\b|\bevery week\b|\b1 week\b(?! free)"),
+    ("month", r"/\s?mo(?:nth)?\b|\bper month\b|\ba month\b|\bmonthly\b|\bevery month\b|\bmo\.?\b|\b1 month\b"),
+    ("quarter", r"\bper quarter\b|\bquarterly\b|\b3 months\b|/\s?3\s?mo\b"),
+    ("half-year", r"\b6 months\b|/\s?6\s?mo\b|\bhalf[- ]year(?:ly)?\b"),
+    ("year", r"/\s?y(?:ea)?r\b|\bper year\b|\ba year\b|\byearly\b|\bannual(?:ly)?\b|\bevery year\b|\b12 months\b"
+             r"|\b1 year\b"),
+    ("lifetime", r"\blifetime\b|\bone[- ]time\b|\bpay once\b|\bforever\b"),
+)
+_PERIODS = [(name, re.compile(pattern, re.I)) for name, pattern in PERIODS]
+TRIAL = re.compile(r"\b(?P<n>\d{1,2}|one|two|three|seven|fourteen|thirty)[- ](?P<unit>day|week|month)s?\b"
+                   r"(?:[- ]long)?\s+(?:free\s+)?trial\b|"
+                   r"\bfree (?:for )?(?P<n2>\d{1,2})[- ](?P<unit2>day|week|month)s?\b"
+                   r"|\b(?P<n3>\d{1,2})[- ](?P<unit3>day|week|month)s? free\b|\bfree trial\b|\btry (?:it )?free\b",
+                   re.I)
+WORDS_N = {"one": 1, "two": 2, "three": 3, "seven": 7, "fourteen": 14, "thirty": 30}
+SELLS = re.compile(r"\b(subscribe|subscription|restore purchases?|free trial|start (?:my |your )?(?:free )?trial|"
+                   r"try (?:it )?free|premium|pro\b|plus\b|unlock|upgrade|unlimited|cancel any ?time|"
+                   r"billed|auto[- ]renew|renews?)\b", re.I)
+RESTORE = re.compile(r"\brestore purchases?\b|\brestore\b", re.I)
+PLAN_NAME = re.compile(r"\b(weekly|monthly|quarterly|yearly|annual|annually|lifetime|family|individual|student|"
+                       r"basic|standard|premium|pro|plus|ultimate|starter)\b", re.I)
+NEAR = 2
+MONTHS = {"week": 12 / 52, "month": 1, "quarter": 3, "half-year": 6, "year": 12}
+
+
+@dataclass
+class Plan:
+    price: str                 # as shown: "$59.99"
+    amount: float              # 59.99
+    currency: str              # "USD"
+    period: str = ""           # week, month, quarter, half-year, year, lifetime, or "" when the screen doesn't say
+    trial: str = ""            # "7 days", "1 week", "free trial"
+    name: str = ""             # "Annual", "Premium"
+    per_month: float = 0.0     # the price spread over a month (0 for lifetime or an unknown period)
+    line: str = ""             # the line the price was read from
+
+    def key(self):
+        """What a plan is across two crawls: its period, else its name, else its place."""
+        return self.period or self.name.casefold() or self.line.casefold()
+
+
+@dataclass
+class Paywall:
+    plans: list = field(default_factory=list)
+    trial: str = ""            # the screen's trial, when it names one apart from a plan
+    restore: bool = False      # a Restore Purchases control is shown
+    signals: list = field(default_factory=list)  # why it reads as a paywall, for the report
+    headline: str = ""         # the screen's first long line ("Unlock everything with Premium")
+
+    def to_json(self):
+        return {**asdict(self), "plans": [asdict(plan) for plan in self.plans]}
+
+
+def _amount(text):
+    """'1,299.99' -> 1299.99; '9,99' -> 9.99; '1 299' -> 1299."""
+    text = text.replace("\u00a0", "").replace(" ", "")
+    cents = re.search(r"[.,](\d{1,2})$", text)
+    whole = re.sub(r"[.,]", "", text[:cents.start()] if cents else text)
+    try:
+        return float(whole + ("." + cents.group(1) if cents else ""))
+    except ValueError:
+        return 0.0
+
+
+def prices(line):
+    """Every price in ``line``: [(shown, amount, currency, start, end)]."""
+    found = []
+    for match in PRICE.finditer(line):
+        symbol = match.group("pre") or match.group("post") or ""
+        amount = _amount(match.group("a1") or match.group("a2") or "")
+        if amount <= 0:
+            continue
+        currency = SYMBOLS.get(symbol, symbol.upper())
+        found.append((match.group(0).strip(), amount, currency, match.start(), match.end()))
+    return found
+
+
+def period(text):
+    for name, pattern in _PERIODS:
+        if pattern.search(text):
+            return name
+    return ""
+
+
+def trial(text):
+    match = TRIAL.search(text)
+    if not match:
+        return ""
+    n = match.group("n") or match.group("n2") or match.group("n3")
+    unit = match.group("unit") or match.group("unit2") or match.group("unit3")
+    if n and unit:
+        count = WORDS_N.get(n.casefold(), None) or int(n)
+        return f"{count} {unit}{'s' if count != 1 else ''}"
+    return "free trial"
+
+
+def _clean(lines):
+    out = []
+    for line in lines or ():
+        text = " ".join(str(line or "").split())
+        if text:
+            out.append(text[:300])
+    return out
+
+
+def detect(lines):
+    """The screen's paywall, or None. ``lines``: its text in reading order."""
+    lines = _clean(lines)
+    if not lines:
+        return None
+    every = "\n".join(lines)
+    priced = [(index, found) for index, line in enumerate(lines) for found in prices(line)]
+    signals = []
+    if priced:
+        signals.append("price")
+    periods = [name for name, pattern in _PERIODS if pattern.search(every)]
+    if periods and priced:
+        signals.append("billing period")
+    screen_trial = trial(every)
+    if screen_trial:
+        signals.append("free trial")
+    restore = bool(RESTORE.search(every)) and bool(re.search(r"\brestore purchases?\b", every, re.I)
+                                                    or SELLS.search(every))
+    if restore:
+        signals.append("restore purchases")
+    sells = sorted({m.group(1).casefold() for m in SELLS.finditer(every)})
+    if sells:
+        signals.append("sells: " + ", ".join(sells[:4]))
+    is_paywall = bool(priced and (periods or screen_trial or restore or sells)) or bool(
+        restore and (screen_trial or sells and any(s in sells for s in ("subscribe", "subscription"))))
+    if not is_paywall:
+        return None
+    plans, seen = [], {}
+    for index, (shown, amount, currency, start, end) in priced:
+        line = lines[index]
+        own = line[end:end + 24]  # "$9.99/month": the period right after the price is its own
+        near = lines[max(0, index - NEAR):index + NEAR + 1]
+        plan_period = period(own) or period(line) or _nearest(lines, index, period)
+        plan_trial = trial(line) or _nearest(lines, index, trial, reach=1)
+        name_match = PLAN_NAME.search(line) or next((PLAN_NAME.search(text) for text in reversed(near[:NEAR])
+                                                     if PLAN_NAME.search(text)), None)
+        name = name_match.group(1).title() if name_match else ""
+        if not plan_period and name.casefold() in ("weekly", "monthly", "quarterly", "yearly", "annual", "annually",
+                                                    "lifetime"):
+            plan_period = period(name)
+        # A per-month equivalent under an annual price ("$4.99/mo, billed yearly") is the same plan.
+        if re.search(r"\bbilled (?:annually|yearly)\b|\bequivalent\b|\bjust\b.*\bper\b", line, re.I) and plans:
+            continue
+        key = (shown, plan_period)
+        if key in seen:
+            # The same price again ("7-day free trial, then $59.99/year"): one plan.
+            known = seen[key]
+            known.trial = known.trial or plan_trial
+            known.name = known.name or name
+            continue
+        per_month = round(amount / MONTHS[plan_period], 2) if plan_period in MONTHS else 0.0
+        plans.append(Plan(price=shown, amount=amount, currency=currency, period=plan_period, trial=plan_trial,
+                          name=name, per_month=per_month, line=line))
+        seen[key] = plans[-1]
+    headline = next((line for line in lines if len(line.split()) >= 3 and not prices(line)), "")
+    return Paywall(plans=plans, trial=screen_trial, restore=restore, signals=signals, headline=headline[:120])
+
+
+def _nearest(lines, index, read, reach=NEAR):
+    for distance in range(1, reach + 1):
+        for other in (index + distance, index - distance):
+            if 0 <= other < len(lines):
+                if prices(lines[other]) and distance > 0:
+                    continue
+                value = read(lines[other])
+                if value:
+                    return value
+    return ""