mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/login.py

@@ -0,0 +1,354 @@
+"""`mobster login`, `mobster login status` and `mobster logout`: your model key, saved for Mobster on this Mac."""
+
+import json
+import os
+import sys
+
+PROVIDERS = {
+    "anthropic": {"name": "Claude", "company": "Anthropic", "variable": "ANTHROPIC_API_KEY", "prefix": "sk-ant-",
+                  "console": "the Claude Console", "url": "https://platform.claude.com/settings/keys"},
+    "openai": {"name": "OpenAI", "company": "OpenAI", "variable": "OPENAI_API_KEY", "prefix": "sk-",
+               "console": "the OpenAI Platform", "url": "https://platform.openai.com/api-keys"},
+}
+ORDER = ("anthropic", "openai")
+
+
+def mask(key):
+    """sk-ant-…a1F2: the key's well-known prefix and its last four characters, never more."""
+    key = (key or "").strip()
+    if len(key) < 12:
+        return "…" + key[-2:] if key else ""
+    for prefix in ("sk-ant-", "sk-proj-", "sk-svcacct-", "sk-"):
+        if key.startswith(prefix):
+            return f"{prefix}…{key[-4:]}"
+    return f"…{key[-4:]}"
+
+
+def source_words(variable):
+    """Where a saved key came from, in words: Mobster for Mac's settings, an env file, or your shell."""
+    from .config import SOURCES
+    source = SOURCES.get(variable)
+    if source == "mac-app":
+        return "from Mobster for Mac"
+    if source == "env-file":
+        return "from your env file"
+    return "from your shell"
+
+
+# The CLI agents sign in with their own CLI: Mobster only runs them (ai_plans/agents.py).
+CLI_SIGN_IN = {"codex": ("Codex", "codex login"),
+               "claude_code": ("Claude Code", "claude, then /login"), "claude": ("Claude Code", "claude, then /login"),
+               "gemini": ("Gemini CLI", "gemini, then choose Sign in with Google")}
+
+
+def run(args):
+    action = getattr(args, "action", None)
+    if args.command == "logout":
+        account = getattr(args, "account", None)
+        if account:
+            return logout_provider(account)
+        return logout(args)
+    if action == "status":
+        return status(args)
+    if action in CLI_SIGN_IN:
+        name, command = CLI_SIGN_IN[action]
+        print(f"{name} signs in itself: in Terminal, run {command}. Mobster runs your {name} from then on; it never "
+              "sees your sign-in.")
+        return 0
+    if action:
+        return login_provider(args, action)
+    return login(args)
+
+
+def login_provider(args, provider_id):
+    """`mobster login <plan or provider>`."""
+    import sys
+
+    from .ai_plans import device_login, providers, routes
+    paint = _paint()
+    provider = providers.get(provider_id)
+    if provider is None:
+        known = ", ".join(sorted(["codex", "claude", "gemini", *providers.ALL]))
+        print(f"mobster login: no plan or provider called {provider_id}. Try one of: {known}", file=sys.stderr)
+        return 2
+    body = {}
+    if getattr(args, "model", None):
+        body["model"] = args.model
+    if getattr(args, "base_url", None):
+        body["baseUrl"] = args.base_url
+    try:
+        if provider.mechanism == "device":
+            attempt = device_login.start(provider.id)
+            print(paint(f"Sign in to {provider.name}", "bold") + ": open " + paint(attempt["url"], "accent")
+                  + " and enter " + paint(attempt["user_code"], "bold") + ".")
+            print("  " + paint("Waiting for you to finish. ctrl+c cancels.", "tertiary"), flush=True)
+            device_login.wait(provider.id, attempt)
+            if body:
+                routes.handle(_keys(), provider.id, "key", body)
+        else:
+            if provider.mechanism in ("key", "custom"):
+                if getattr(args, "with_key", False):
+                    key = sys.stdin.read().strip()
+                else:
+                    import getpass
+                    where = f" (from {provider.console})" if provider.console else ""
+                    key = getpass.getpass(f"Paste your {provider.name} key{where}: ").strip()
+                body["key"] = key
+            routes.handle(_keys(), provider.id, "key", body)
+        routes.handle(_keys(), provider.id, "use", {})
+    except KeyboardInterrupt:
+        print()
+        print(paint("Cancelled. Nothing was saved.", "tertiary"))
+        return 130
+    except (routes.RouteError, device_login.DeviceError) as error:
+        print(paint("✗ ", "coral", "bold") + str(error))
+        return 1
+    model = providers.chosen_model(provider)
+    vision = "" if provider.vision(model) else " It can't see images, so it reads the screen as text."
+    bill = f"on {provider.plan_label}" if provider.group == "plan" else f"on your {provider.name} key"
+    print(paint("✓ ", "green", "bold") + f"Mobster's agent runs on {model}, {bill}.{vision}")
+    return 0
+
+
+def logout_provider(provider_id):
+    import sys
+
+    from .ai_plans import providers, routes
+    if providers.get(provider_id) is None:
+        print(f"mobster logout: no plan or provider called {provider_id}.", file=sys.stderr)
+        return 2
+    routes.handle(_keys(), provider_id, "forget", {})
+    print(f"Mobster forgot {providers.get(provider_id).name} on this Mac.")
+    return 0
+
+
+def _paint(stream=None):
+    from .style import palette
+    return palette(stream or sys.stdout)
+
+
+def _keys():
+    from .config import app_env_file
+    from .keys import Keys
+    return Keys(app_env_file())
+
+
+def _saved():
+    """{variable: value} in the Mac app's settings file (not the shell's)."""
+    from .config import app_env_file
+    path = app_env_file()
+    values = {}
+    wanted = {p["variable"] for p in PROVIDERS.values()} | {"MOBSTER_SMART_PROVIDER"}
+    try:
+        for line in path.read_text(encoding="utf-8").splitlines():
+            name, sep, value = line.partition("=")
+            if sep and name.strip() in wanted:
+                values[name.strip()] = value.strip().strip("'\"")
+    except (OSError, UnicodeDecodeError):
+        pass
+    # The keys themselves are in the Keychain once the Mac app or this command saved them there (env_secrets.py).
+    from . import env_secrets
+    values.update({name: value for name, value in env_secrets.load(path).items() if name in wanted})
+    return values
+
+
+def status(args):
+    """Masked rows: which keys Mobster can use, and which one its agent uses."""
+    from .engines import model_provider, smart_model
+    paint = _paint()
+    rows = []
+    for provider in ORDER:
+        info = PROVIDERS[provider]
+        key = os.environ.get(info["variable"], "").strip()
+        rows.append({"provider": provider, "name": info["name"], "set": bool(key), "key": mask(key) if key else None,
+                     "source": source_words(info["variable"]) if key else None})
+    from .ai_plans import providers
+    ready = [row for row in providers.public() if row["configured"]]
+    smart = model_provider(smart_model()) if any(r["set"] for r in rows) or ready else None
+    if getattr(args, "json", False):
+        print(json.dumps({"keys": rows, "agent": smart, "model": smart_model() if smart else None,
+                          "providers": [{key: row[key] for key in ("id", "name", "model", "vision")}
+                                        for row in ready]}))
+        return 0
+    print(paint("Keys", "bold"))
+    for row in rows:
+        name = paint(row["name"].ljust(8), "accent")
+        if row["set"]:
+            note = "  Mobster's agent uses it" if row["provider"] == smart else ""
+            print(f"  {paint('✓', 'green')} {name}{row['key'].ljust(16)}{paint(row['source'], 'tertiary')}"
+                  + paint(note, "secondary"))
+        else:
+            print(f"  {paint('–', 'tertiary')} {name}{paint('not set', 'tertiary')}")
+    if ready:
+        print(paint("Plans and providers", "bold"))
+        for row in ready:
+            uses = paint("  Mobster's agent uses it", "secondary") if smart == row["id"] else ""
+            vision = "" if row["vision"] else paint("  reads the screen as text", "tertiary")
+            print(f"  {paint('✓', 'green')} {row['name']}  {row['model']}{vision}{uses}")
+    if not any(row["set"] for row in rows) and not ready:
+        print("\nNo key yet. Run " + paint("mobster login", "accent") + ", or pick Codex or Claude Code in the Mac "
+              "app's composer to run on your plan.")
+    return 0
+
+
+def _choose(paint):
+    """Ask which provider, Claude first. Returns anthropic or openai."""
+    print(paint("Which AI do you use?", "bold"))
+    print("  " + paint("1", "accent") + "  Claude, by Anthropic   " + paint("recommended", "green"))
+    print("  " + paint("2", "accent") + "  OpenAI")
+    while True:
+        try:
+            answer = input("Choose 1 or 2 [1]: ").strip()
+        except EOFError:
+            return None
+        if answer in ("", "1", "claude", "anthropic"):
+            return "anthropic"
+        if answer in ("2", "openai"):
+            return "openai"
+
+
+def save_key(provider, key, *, check=True):
+    """Check a pasted key and save it, as `mobster login` and the terminal UI both do."""
+    from .env_secrets import REFUSED, KeychainError
+    from .keys import KEY_PATTERN
+    info = PROVIDERS[provider]
+    if not key or not KEY_PATTERN.fullmatch(key):
+        return {"ok": False, "problem": "pattern", "message":
+                f"That doesn't look like {'an' if provider == 'openai' else 'a'} {info['name']} key. "
+                "Copy it again, without spaces."}
+    variable = info["variable"]
+    saved = {name: os.environ.get(name) for name in (variable, "MOBSTER_SMART_PROVIDER")}
+    os.environ[variable], os.environ["MOBSTER_SMART_PROVIDER"] = key, provider
+
+    def fail(result):
+        for name, value in saved.items():
+            if value is None:
+                os.environ.pop(name, None)
+            else:
+                os.environ[name] = value
+        return {"ok": False, **result}
+
+    keys = _keys()
+    if check:
+        try:
+            result = keys.test(provider)
+        except Exception as error:  # noqa: BLE001 -- the test's own words, or a plain one
+            result = {"ok": False, "message": f"Mobster couldn't check the key ({type(error).__name__})."}
+        if not result.get("ok"):
+            return fail({"problem": result.get("problem"), "link": result.get("link"),
+                         "message": (result.get("message") or "The key didn't work.") + " Nothing was saved."})
+    try:
+        keys.update({provider: {"key": key}, "smartProvider": provider})
+    except KeychainError:
+        return fail({"problem": "keychain", "message": REFUSED})
+    from .config import SOURCES
+    SOURCES[variable] = "mac-app"
+    return {"ok": True, "problem": None, "message": f"{info['name']} is connected."}
+
+
+def login(args):
+    paint = _paint()
+    provider = args.provider
+    if args.with_key:
+        if sys.stdin.isatty():
+            print("mobster login: --with-key reads the key from a pipe or a file, not the keyboard: "
+                  "mobster login --with-key < key.txt", file=sys.stderr)
+            return 2
+        key = sys.stdin.read().strip()
+        provider = provider or _guess(key) or "anthropic"
+    else:
+        if not sys.stdin.isatty():
+            print("mobster login: this asks for your key, so it needs a terminal. In a script: "
+                  "mobster login --provider anthropic --with-key < key.txt", file=sys.stderr)
+            return 2
+        print("Mobster's agent runs on your own Claude or OpenAI key.")
+        print("You pay them for what it uses, and the key stays on this Mac.")
+        print()
+        if provider is None:
+            try:
+                provider = _choose(paint)
+            except KeyboardInterrupt:
+                print()
+                print(paint("Nothing was saved.", "tertiary"))
+                return 130
+            if provider is None:
+                return 2
+            print()
+        info = PROVIDERS[provider]
+        print(paint(f"Get a key from {info['console']}: ", "tertiary") + paint(info["url"], "accent"))
+        import getpass
+        try:
+            key = getpass.getpass(f"Paste your {info['name']} key" + (f" (it starts with {info['prefix']}; "
+                                  if info["prefix"] else " (") + "it isn't shown): ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print()
+            print(paint("Nothing was saved.", "tertiary"))
+            return 130
+    info = PROVIDERS[provider]
+    if not args.skip_check and not args.json:
+        print(paint("Checking your key…", "tertiary"), flush=True)
+    result = save_key(provider, key, check=not args.skip_check)
+    if result["problem"] == "pattern":
+        print(f"mobster login: {result['message']}", file=sys.stderr)
+        return 2
+    if not result["ok"]:
+        if args.json:
+            print(json.dumps({"ok": False, "provider": provider, "message": result["message"],
+                              "problem": result["problem"]}))
+        else:
+            print(paint("✗ ", "coral", "bold") + result["message"])
+            link = result.get("link")
+            if isinstance(link, dict) and link.get("url"):
+                print("  " + paint(link["url"], "accent"))
+        return 1
+    if args.json:
+        print(json.dumps({"ok": True, "provider": provider, "key": mask(key), "checked": not args.skip_check}))
+        return 0
+    from .engines import smart_model
+    print(paint("✓ ", "green", "bold") + paint(f"{info['name']} is connected", "bold") + f", key {mask(key)}, "
+          f"{smart_model()}")
+    print("  " + paint("Saved on this Mac in Mobster's settings file (only you can read it). Mobster for Mac and "
+                       "every `mobster` command use it.", "tertiary"))
+    print("  Next: " + paint("mobster doctor", "accent") + " checks your iPhone, or " + paint("mobster", "accent")
+          + " gives it a task.")
+    return 0
+
+
+def _guess(key):
+    if key.startswith("sk-ant-"):
+        return "anthropic"
+    if key.startswith("sk-"):
+        return "openai"
+    return None
+
+
+def logout(args):
+    """Remove one saved key from the settings file Mobster for Mac and `mobster login` share."""
+    from .engines import model_provider, smart_model
+    paint = _paint()
+    saved = _saved()
+    provider = args.provider
+    if provider is None:
+        known = [name for name in ORDER if PROVIDERS[name]["variable"] in saved]
+        chosen = model_provider(smart_model())
+        # A plan or another provider can be selected for Smart: it names no key here, so only a sole key is removed.
+        provider = chosen if chosen in known else known[0] if len(known) == 1 else None
+        if provider is None and known:
+            print("mobster logout: more than one key is saved. Choose one with --provider "
+                  + ", ".join(known) + ".", file=sys.stderr)
+            return 2
+    if provider is None:
+        print("No key is saved for Mobster on this Mac.")
+        return 0
+    if PROVIDERS[provider]["variable"] not in saved:
+        print(f"No {PROVIDERS[provider]['name']} key is saved for Mobster on this Mac.")
+        if os.environ.get(PROVIDERS[provider]["variable"]):
+            print("  " + paint(f"One is set in your shell or an env file ({PROVIDERS[provider]['variable']}); "
+                               "remove it there.", "tertiary"))
+        return 0
+    changes = {provider: None}
+    if saved.get("MOBSTER_SMART_PROVIDER") == provider:
+        changes["smartProvider"] = None
+    _keys().update(changes)
+    print(paint("✓ ", "green", "bold") + f"Removed the {PROVIDERS[provider]['name']} key from this Mac.")
+    return 0

mobile_agent/longform/__init__.py

@@ -0,0 +1,15 @@
+"""Long-form tasks (track ``longform``, DESIGN.md)."""
+
+TRACK = "longform"
+
+
+def enabled():
+    """Whether long tasks run: the track is loaded and on (its run field is registered), and ``MOBSTER_LONGFORM``
+    isn't "off" (the switch the benchmark's "before" runs can use; every task then runs as it did before long
+    tasks)."""
+    import os
+    if os.environ.get("MOBSTER_LONGFORM", "").strip().casefold() in ("off", "0", "false", "no"):
+        return False
+    from .. import harness_api
+    return not harness_api.disabled(TRACK) and TRACK in harness_api.run_fields()
+

mobile_agent/longform/ads.py

@@ -0,0 +1,191 @@
+"""Reading one feed item (Reels, TikTok, Shorts): who made it, what it says, whether it is an ad (DESIGN.md § 7.3)."""
+
+import re
+from dataclasses import dataclass, field
+
+AD_LABEL = re.compile(r"^\s*(sponsored|ad|promoted|advertisement)\s*$", re.I)
+PAID = re.compile(r"\bpaid partnership\b", re.I)
+CTA = re.compile(r"^\s*(shop now|learn more|install now|install|sign up|book now|order now|get offer|download|"
+                 r"visit (site|advertiser|website)|apply now|watch more|get quote|contact us|"
+                 r"subscribe now)\s*[›>]?\s*$",
+                 re.I)
+HANDLE = re.compile(r"^@?([A-Za-z0-9._]{2,30})$")
+# Signs of a full-screen video that name no app (10 Oct, one general engine): a screen-covering element whose label or
+# identifier says video ("sundial-viewer-video-cell": Instagram's viewer opened from search, which its item label
+# missed), and a small "Post by name" control naming the creator.
+VIDEO_SURFACE = re.compile(r"(?:^|[\s_-])video(?:[\s_-]|$)", re.I)
+BY_HANDLE = re.compile(r"^(?:reel|video|post|short|tiktok) by @?([\w.]{2,30})$", re.I)
+# More bylines no app names (real iPhone, 13 Oct: a collab Reel showed no "@handle", only these): a creator's
+# picture ("42ledger. Profile picture") and a collab line ("42ledger and fahaadk_"); the first creator is the item's.
+PICTURE_OF = re.compile(r"^@?([\w.]{2,30}?)\.?,? profile picture$", re.I)
+COLLAB = re.compile(r"^@?([\w.]{2,30}) and @?([\w.]{2,30})$", re.I)
+# A playing video's progress bar ("Video progress: 11 percent"): the screen is a video item, whatever its labels.
+PROGRESS = re.compile(r"^video progress\b", re.I)
+# "Followed by simon": who of the person's follows follows the creator; that person is not the creator.
+FOLLOWED_BY = re.compile(r"^followed by @?([\w.]{2,30})\b", re.I)
+# An accessibility identifier read as a label ("simon, clips_viewer_clips_tab"): a control's name, never a caption.
+IDENTIFIER = re.compile(r"\b[a-z]+(?:_[a-z]+){2,}\b|^[a-z0-9]+(?:-[a-z0-9]+){2,}$")
+# The control that expands a collapsed caption: never the caption itself.
+MORE_CAPTION = re.compile(r"^more,? (button,? )?tap to see the (whole|full) caption$", re.I)
+
+
+@dataclass(frozen=True)
+class Hints:
+    item: re.Pattern            # the full-screen element's label ("Reel by @hoopslab")
+    item_area: float            # or any element covering this share of the screen
+    creator: re.Pattern         # a label that names the creator; group 1 is the handle
+    audio: re.Pattern           # the audio line
+    chrome: re.Pattern          # controls and labels that are never the caption
+    min_caption: int = 8
+
+
+_CHROME = (r"^(like|liked|unlike|comment|comments|share|send|save|saved|save post|repost|remix|more|more options|"
+           r"more actions|"
+           r"options|follow|"
+           r"following|back|close|reels|for you|following|friends|home|search|explore|inbox|profile|shop|create|"
+           r"camera|mute|unmute|sound|pause|play|subscribe|subscribed|dislike|shorts|\d[\d.,]*[kmb]?|"
+           r"original audio|see translation|view insights|boost reel|"
+           r"\d[\d.,]*[kmb]? (likes?|comments?|shares?|views?|plays?|reposts?|saves?))$")
+
+# One reader for every app (one general engine, 10 Oct: the per-app hints for Instagram, TikTok and YouTube are gone).
+# What a feed item shows is the same everywhere: a full-screen element named "Reel/Video/Post/Short/TikTok by
+# @name" or a video surface, a creator handle, a caption, an audio or sound line, and the controls around it.
+GENERIC = Hints(item=re.compile(r"^(reel|video|short|post|tiktok) by @?[\w.]+", re.I), item_area=.8,
+                creator=re.compile(r"^(?:reel by |video by |post by )?@([\w.-]{2,30})$", re.I),
+                audio=re.compile(r"(♫|♪|original (audio|sound)|\baudio\b|\bsound\b)", re.I),
+                chrome=re.compile(_CHROME, re.I))
+
+
+@dataclass
+class ItemRead:
+    """One screen of a feed, read: None where the tree doesn't say."""
+    full_screen: bool = False
+    creator: str | None = None
+    caption: str | None = None
+    audio: str | None = None
+    ad: str | None = None             # why it is an ad, or None
+    sponsored: bool = False           # a paid partnership: kept, flagged
+    overlay: str | None = None        # an Alert or Sheet over the feed
+    item_label: bool = False          # the full-screen element is labelled as an item ("Reel by @hoopslab"), or a
+                                      # video's progress bar shows
+    lines: list = field(default_factory=list)   # every distinct text, top to bottom (for the extractor)
+
+    def signals(self):
+        """How many of a feed item's signs this screen shows: a creator, a caption or audio line, an item label."""
+        return int(bool(self.creator)) + int(bool(self.caption or self.audio)) + int(self.item_label)
+
+    def ax_text(self):
+        parts = []
+        if self.creator:
+            parts.append(f"Creator: @{self.creator}")
+        if self.caption:
+            parts.append(f"Caption: {self.caption}")
+        if self.audio:
+            parts.append(f"Audio: {self.audio}")
+        if self.sponsored:
+            parts.append("Labelled: Paid partnership")
+        rest = [line for line in self.lines if line not in (self.caption, self.audio)
+                and not (self.creator and line.lstrip("@") == self.creator)]
+        if rest:
+            parts.append("Other text: " + " | ".join(rest[:12]))
+        return "\n".join(parts)
+
+
+def _within(rect, outer):
+    x, y, w, h = rect
+    ox, oy, ow, oh = outer
+    return ox - .01 <= x + w / 2 <= ox + ow + .01 and oy - .01 <= y + h / 2 <= oy + oh + .01
+
+
+def _text(element):
+    label = " ".join((getattr(element, "label", "") or "").split())
+    value = " ".join((getattr(element, "value", "") or "").split())
+    return label if not value or value == label else f"{label} {value}".strip()
+
+
+def read(snapshot, hints):
+    """``snapshot`` (one screen of the feed) as an ItemRead, by ``hints``."""
+    out = ItemRead()
+    bylines, pictures, followed = [], [], set()
+    surface = None
+    elements = sorted(getattr(snapshot, "elements", ()) or (), key=lambda e: (e.rect[1], e.rect[0]))
+    captions = []
+    for element in elements:
+        role = (element.role or "").removeprefix("XCUIElementType")
+        text = _text(element)
+        if role in ("Alert", "Sheet"):
+            out.overlay = out.overlay or (text or role)
+            continue
+        x, y, w, h = element.rect
+        # A full-screen item is one the tree names as an item, or a video. An app's root "Other" (or a big cell or
+        # picture) covers the screen in almost every app: a home feed, DMs, Stories and card stacks aren't feeds.
+        if w * h >= hints.item_area:
+            if hints.item.match(text) or role == "Video" or VIDEO_SURFACE.search(text):
+                out.full_screen = True
+                # Named as an item ("Reel by @name"), or as a video surface: a screen-covering video is an item's sign.
+                out.item_label = out.item_label or bool(hints.item.match(text)) or role == "Video" \
+                    or bool(VIDEO_SURFACE.search(text))
+                surface = surface or element.rect
+                match = re.search(r"@([\w.-]{2,30})", text)
+                if match and not out.creator:
+                    out.creator = match.group(1)
+            continue        # a container as big as the screen: its label is never the item's caption
+        if PROGRESS.match(text):
+            out.item_label = True      # a playing video's own progress bar
+            continue
+        if MORE_CAPTION.match(text) or IDENTIFIER.search(text):
+            continue
+        social = FOLLOWED_BY.match(text)
+        if social:
+            followed.add(social.group(1).casefold())
+            continue
+        picture = PICTURE_OF.match(text)
+        if picture and role in ("Button", "Image", "Link", "Other"):
+            pictures.append(picture.group(1))
+            continue
+        collab = COLLAB.match(text)
+        if collab and not out.creator and role in ("Button", "StaticText", "Link", "Other") and len(text) <= 64:
+            out.creator = collab.group(1)
+            continue
+        if not text or hints.item.match(text):     # a thumbnail of another item (a grid), not this item's text
+            if text and BY_HANDLE.match(text):
+                bylines.append(BY_HANDLE.match(text).group(1))
+            continue
+        if AD_LABEL.match(text):
+            out.ad = out.ad or text.strip()
+            continue
+        if PAID.search(text):
+            out.sponsored = True
+            continue
+        if CTA.match(text) and role in ("Button", "Link", "Other", "StaticText"):
+            out.ad = out.ad or text.strip()
+            continue
+        creator = hints.creator.match(text)
+        if creator and role in ("Button", "StaticText", "Link") and not out.creator:
+            out.creator = creator.group(1)
+            continue
+        if hints.audio.search(text) and not out.audio and len(text) <= 120:
+            out.audio = text
+            continue
+        if hints.chrome.match(text):
+            continue
+        if text not in out.lines:
+            out.lines.append(text[:300])
+        if role in ("StaticText", "TextView", "Other", "Button") and len(text) >= hints.min_caption:
+            captions.append((text, element.rect))
+    if surface is not None:
+        # The item's own text sits on it; a tab bar or a toolbar below a feed that leaves room for one is not a caption.
+        captions = [(text, rect) for text, rect in captions if _within(rect, surface)]
+    if captions:
+        out.caption = max((text for text, _ in captions), key=len)[:300]
+    if not out.creator and len(set(bylines)) == 1:
+        out.creator = bylines[0]  # one "Post by name" on the screen is its item's creator (a grid has many)
+    pictures = [name for name in pictures if name.casefold() not in followed]
+    if not out.creator and out.full_screen and 1 <= len(set(pictures)) <= 2:
+        out.creator = pictures[-1]  # the creator's picture beside the caption (a collab shows two; the lower is first)
+    return out
+
+
+def ad_reason(item_read):
+    """Why this item is an ad ("Sponsored", "Shop now"), or None. A paid partnership is not an ad."""
+    return item_read.ad