mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/verify/source_observation.py

@@ -0,0 +1,130 @@
+"""Audit each XML source read a verification driver actually makes, without another WDA request."""
+
+import threading
+from urllib.parse import parse_qsl, urlencode, urlsplit
+
+from .tree import parse_tree
+
+
+def _xml_source(path):
+    if not isinstance(path, str):
+        return None
+    parts = urlsplit(path)
+    if parts.scheme or parts.netloc or parts.path != "/source":
+        return None
+    query = parse_qsl(parts.query, keep_blank_values=True)
+    if [value for key, value in query if key == "format"] != ["xml"]:
+        return None
+    # Keep the caller's other source options; only attributes omitted for fast grounding are restored.
+    query = [(key, value) for key, value in query if key != "excluded_attributes"]
+    query.append(("excluded_attributes", "accessible,index"))
+    return parts.path + "?" + urlencode(query, safe=",")
+
+
+class SourceObservation:
+    """A private, run-owned adapter around a driver's bound call/observe methods."""
+
+    def __init__(self, run):
+        self.run = run
+        self.driver = None
+        self._originals = {}
+        self._wrappers = {}
+        self._local = threading.local()
+        self._active = False
+
+    @property
+    def active(self):
+        return self._active
+
+    def attach(self, driver):
+        if self.driver is driver and self._active:
+            return True
+        if getattr(driver, "_verify_source_owner", None) is not None or not callable(getattr(driver, "call", None)):
+            self.run._incomplete_screen("The driver could not expose its accessibility source reads")
+            return False
+        try:
+            owned = vars(driver)
+        except TypeError:
+            # Restoring inherited methods requires knowing which attributes the instance owned before wrapping.
+            self.run._incomplete_screen("The driver could not expose its accessibility source reads")
+            return False
+        originals = {"call": ("call" in owned, driver.call)}
+        observe = getattr(driver, "observe", None)
+        if callable(observe):
+            originals["observe"] = ("observe" in owned, observe)
+
+        def call(method, path, *args, **kwargs):
+            source = _xml_source(path) if isinstance(method, str) and method.upper() == "GET" else None
+            if source is None:
+                return originals["call"][1](method, path, *args, **kwargs)
+            release = self.run._reserve_source_read()
+            try:
+                xml = originals["call"][1](method, source, *args, **kwargs)
+                if release is not None and self._active:
+                    try:
+                        tree = parse_tree(xml)
+                        self.run._observe_screen(None, tree)
+                        self._local.sources = getattr(self._local, "sources", 0) + 1
+                    except Exception as error:
+                        self.run.log(f"source audit skipped: {type(error).__name__}")
+                        self.run._incomplete_screen("An accessibility source could not be audited")
+                return xml
+            except BaseException:
+                if release is not None and self._active:
+                    self.run._incomplete_screen("An accessibility source request failed")
+                raise
+            finally:
+                if release is not None:
+                    release()
+
+        wrappers = {"call": call}
+        if "observe" in originals:
+            def observed(*args, **kwargs):
+                before = getattr(self._local, "sources", 0)
+                release = self.run._reserve_source_read()
+                try:
+                    snapshot = originals["observe"][1](*args, **kwargs)
+                    if release is not None and self._active:
+                        from ..state import PIXEL_SOURCES
+                        if (getattr(snapshot, "source", None) in PIXEL_SOURCES
+                                or getattr(self._local, "sources", 0) == before):
+                            self.run._incomplete_screen("A screen read had no complete accessibility source")
+                    return snapshot
+                except BaseException:
+                    if release is not None and self._active:
+                        self.run._incomplete_screen("A screen observation failed")
+                    raise
+                finally:
+                    if release is not None:
+                        release()
+
+            wrappers["observe"] = observed
+        try:
+            for name, wrapper in wrappers.items():
+                setattr(driver, name, wrapper)
+            driver._verify_source_owner = self
+        except (AttributeError, TypeError):
+            for name, (own, original) in originals.items():
+                if getattr(driver, name, None) is wrappers.get(name):
+                    if own:
+                        setattr(driver, name, original)
+                    else:
+                        delattr(driver, name)
+            self.run._incomplete_screen("The driver could not expose its accessibility source reads")
+            return False
+        self.driver, self._originals, self._wrappers, self._active = driver, originals, wrappers, True
+        return True
+
+    def detach(self, driver):
+        if self.driver is not driver:
+            return
+        self._active = False
+        if getattr(driver, "_verify_source_owner", None) is self:
+            for name, (own, original) in self._originals.items():
+                if getattr(driver, name, None) is self._wrappers[name]:
+                    if own:
+                        setattr(driver, name, original)
+                    else:
+                        delattr(driver, name)
+            delattr(driver, "_verify_source_owner")
+        self.driver = None

mobile_agent/verify/system_surfaces/__init__.py

@@ -0,0 +1,7 @@
+"""Check steps for the system surfaces an app lives on outside its own window, driven and read on a simulator:
+App Intents, Home Screen widgets, Live Activities, Control Center, App Clips, Spotlight and the share sheet.
+
+Off unless ``MOBSTER_EXPERIMENTAL_SYSTEM_SURFACES=1`` (docs/checks.mdx). A surface is driven from outside the app with
+WebDriverAgent and read from the accessibility tree like any screen, so the assertions are the check language's own.
+``spec`` is the check file's block, ``play`` runs it after the flow. They are imported by name because the check
+loader needs the first before the run machinery the second leans on exists."""

mobile_agent/verify/system_surfaces/play.py

@@ -0,0 +1,106 @@
+"""Run a check's surfaces on the simulator the run holds, after its flow."""
+
+from ..smart import is_real_device
+from ..verdict import CouldntRun
+from . import spec
+from .stage import Stage, SurfaceMiss
+from .surfaces import DRIVERS
+
+NOT_ON_SIMULATOR = "Not on a simulator: "
+
+
+class Context:
+    """What a driver needs from the simulator manager, with its errors as a check failing rather than the run."""
+
+    def __init__(self, run):
+        self.run = run
+
+    def _try(self, what, *args):
+        try:
+            return what(self.run.target, *args)
+        except Exception as error:
+            raise SurfaceMiss(str(error) or type(error).__name__) from None
+
+    def open_url(self, url):
+        self._try(self.run.manager.open_url, url)
+
+    def launch(self, bundle, env):
+        self._try(self.run.manager.launch, bundle, (), env)
+
+    def install(self, path):
+        self._try(self.run.manager.install, path)
+
+
+def refuse_unsupported(run):
+    """The run can't drive these, so it says so before it touches the simulator."""
+    if is_real_device(run.manager):
+        raise CouldntRun("environment", NOT_ON_SIMULATOR + "system surfaces are driven on a simulator. They press, "
+                         "swipe and lock the screen, which Mobster never does on your iPhone.",
+                         "Run the check with --sim.")
+    for surface in run.check.surfaces:
+        via = surface.params.get("via", "url")
+        if surface.kind == "app_clip" and via != "url":
+            raise CouldntRun("environment", NOT_ON_SIMULATOR + f"an App Clip card opened by {via} has no simulator "
+                             "path. Only its invocation URL runs.",
+                             "Use via: url, or test the card on a phone by hand.")
+
+
+def play(run, stage, ctx, surface):
+    """One surface: drive it, tap its ``pick``, and read: (assertion results, the sentence that failed, its frame)."""
+    results, miss, frames = [], None, []
+    stage.shot = lambda: frames.append(run.frame(f"surface-{surface.kind}-{len(frames) + 1}"))
+    try:
+        stage.follow_the_front()
+        results, tree = DRIVERS[surface.kind](stage, surface, ctx)
+        if surface.pick is not None:
+            stage.tap_node(stage.wait_for(None, f"{surface.pick.render()} to pick", selector=surface.pick), "the pick")
+            after, tree = stage.settle(surface.then)
+            results = [*results, *after]
+        elif surface.kind == "share_sheet":
+            stage.tap(tree.size[0] / 2, tree.size[1] * .08, "outside the sheet to close it")
+    except SurfaceMiss as error:
+        miss = str(error)
+    # A CouldntRun (an action with no answer) skips this: nothing more is sent to a simulator in an unknown state.
+    stage.activate(run.app.bundle_id)
+    return results, miss, next((frame for frame in reversed(frames) if frame), None)
+
+
+def finding(surface, text, frame, run):
+    frame = run._relative(frame)
+    return {"id": f"{surface.label()}", "guideline": None, "level": "fail", "frame": frame,
+            "message": f"{surface.label()}: {text}", "evidence": frame or "the surface"}
+
+
+def drive(run):
+    """Every surface in order. A surface that fails adds a fail finding and the next one still runs; a refused
+    environment or an action with no answer ends the run."""
+    surfaces = run.check.surfaces
+    if not surfaces:
+        return
+    if not spec.enabled():
+        raise CouldntRun("usage", f"The check has surfaces, which are off. Set {spec.FLAG}=1.")
+    refuse_unsupported(run)
+    from ..runner import _now  # the run's own clock, so a test that sets it sets this one too
+    stage = Stage(run.driver, log=run.log, sleep=run._sleep, clock=_now)
+    ctx = Context(run)
+    run.surface_reports = []
+    with run.lock:
+        for surface in surfaces:
+            run._check_stop()
+            results, miss, frame = play(run, stage, ctx, surface)
+            failed = [item for item in results if not item.ok]
+            run.event({"event": "surface", "surface": surface.kind, "name": surface.label(),
+                       "held": len(results) - len(failed), "failed": len(failed), "miss": miss})
+            run.log(f"surface {surface.label()}: {len(results) - len(failed)} of {len(results)} held"
+                    + (f"; {miss}" if miss else ""))
+            if miss:
+                run.findings.append(finding(surface, miss, frame, run))
+            for item in failed:
+                run.findings.append(finding(surface, f"{item.text}: {item.observed}", frame, run))
+            run.surface_reports.append({"surface": surface.kind, "name": surface.label(), "ok": not (miss or failed)})
+
+
+def note(run):
+    """The verdict's tail for a run that drove surfaces: how many held."""
+    reports = getattr(run, "surface_reports", ())
+    return f"; {sum(item['ok'] for item in reports)} of {len(reports)} system surfaces held" if reports else ""

mobile_agent/verify/system_surfaces/spec.py

@@ -0,0 +1,139 @@
+"""The ``surfaces`` block of a check: which system surfaces to drive and what must show on each."""
+
+import difflib
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+from ..assertions import CheckError, expand_assertion, parse_selector, reject_unknown_keys
+
+FLAG = "MOBSTER_EXPERIMENTAL_SYSTEM_SURFACES"
+LIMIT = 10
+WHERE = ("lock_screen", "dynamic_island")
+# App Clip invocations that need a phone, a tag or a place; only the URL has a simulator path.
+VIA_UNSUPPORTED = ("nfc", "qr", "banner", "maps")
+VIA = ("url", *VIA_UNSUPPORTED)
+
+COMMON = ("surface", "name", "expect")
+# kind -> (keys it takes besides COMMON, keys it needs)
+KINDS = {
+    "intent": (("shortcut", "siri", "input"), ()),
+    "widget": (("add",), ()),
+    "live_activity": (("where", "expanded"), ()),
+    "control_center": (("pick", "then"), ()),
+    "app_clip": (("bundle", "url", "via", "path"), ("bundle", "url")),
+    "spotlight": (("query", "pick", "then"), ("query",)),
+    "share_sheet": (("open", "pick", "then"), ("open",)),
+}
+
+
+def enabled():
+    """Whether system surfaces are switched on (``MOBSTER_EXPERIMENTAL_SYSTEM_SURFACES=1``)."""
+    return os.environ.get(FLAG, "").strip().casefold() in ("1", "true", "yes", "on")
+
+
+@dataclass(frozen=True)
+class Surface:
+    kind: str
+    name: str
+    params: dict                                # the validated keys as written, minus expect and then
+    expect: tuple = ()                          # of assertions: what shows once the surface is up
+    then: tuple = ()                            # of assertions: what shows after `pick`
+    pick: Optional[object] = None               # assertions.Selector: the element to tap
+    open: Optional[object] = None               # assertions.Selector: the in-app control that presents the surface
+
+    def label(self):
+        return self.name or self.kind.replace("_", " ")
+
+
+def _text(value, where):
+    if isinstance(value, bool) or not isinstance(value, str) or not value.strip():
+        raise CheckError(f"{where} must be text")
+    if len(value) > 500:
+        raise CheckError(f"{where} is longer than 500 characters")
+    return value.strip()
+
+
+def _selector(value, where):
+    """A label as text, or a selector object."""
+    return parse_selector({"label": value} if isinstance(value, str) else value, where)
+
+
+def _assertions(value, where):
+    if value is None:
+        return ()
+    if not isinstance(value, list):
+        raise CheckError(f"{where} must be a list of assertions, such as [{{text: 12 day streak}}]")
+    out = []
+    for index, item in enumerate(value):
+        out.extend(expand_assertion(item, f"{where}[{index}]"))
+    return tuple(out)
+
+
+def _one(index, item, base_dir):
+    where = f"surfaces[{index}]"
+    if not isinstance(item, dict):
+        raise CheckError(f"{where} must be an object such as {{surface: widget, expect: [{{text: Streak}}]}}")
+    kind = item.get("surface")
+    if kind not in KINDS:
+        close = difflib.get_close_matches(str(kind), list(KINDS), n=1)
+        raise CheckError(f"{where}.surface {kind!r} isn't a system surface; "
+                         + (f"did you mean {close[0]}? " if close else "") + f"Use {', '.join(KINDS)}.")
+    keys, required = KINDS[kind]
+    reject_unknown_keys(item, (*COMMON, *keys), where)
+    for key in required:
+        if item.get(key) is None:
+            raise CheckError(f"{where}.{key} is required for a {kind.replace('_', ' ')}")
+    params = {key: item[key] for key in keys if item.get(key) is not None}
+    if kind == "intent" and ("shortcut" in params) == ("siri" in params):
+        raise CheckError(f"{where} needs exactly one of shortcut (a shortcut's name) and siri (a phrase to say)")
+    if "input" in params and "shortcut" not in params:
+        raise CheckError(f"{where}.input goes with shortcut")
+    if "where" in params and params["where"] not in WHERE:
+        raise CheckError(f"{where}.where must be one of {', '.join(WHERE)}")
+    if "expanded" in params and not isinstance(params["expanded"], bool):
+        raise CheckError(f"{where}.expanded must be true or false")
+    if "via" in params and params["via"] not in VIA:
+        raise CheckError(f"{where}.via must be one of {', '.join(VIA)}")
+    for key in ("shortcut", "siri", "input", "add", "query", "bundle", "url", "path"):
+        if key in params:
+            params[key] = _text(params[key], f"{where}.{key}")
+    if "path" in params and base_dir is not None and not os.path.isabs(params["path"]):
+        params["path"] = os.path.normpath(os.path.join(base_dir, params["path"]))
+    pick = _selector(params["pick"], f"{where}.pick") if "pick" in params else None
+    opens = _selector(params["open"], f"{where}.open") if "open" in params else None
+    then = _assertions(item.get("then"), f"{where}.then")
+    if then and pick is None:
+        raise CheckError(f"{where}.then is read after pick, and there is no pick")
+    expect = _assertions(item.get("expect"), f"{where}.expect")
+    if not (expect or then):
+        raise CheckError(f"{where} checks nothing. Add expect: what must show on the {kind.replace('_', ' ')}")
+    name = item.get("name")
+    return Surface(kind, _text(name, f"{where}.name") if name is not None else "", params,
+                   expect, then, pick, opens)
+
+
+def parse(value, base_dir=None):
+    """The ``surfaces`` block as a tuple of Surface: () when absent. Raises CheckError; off unless the flag is on."""
+    if value is None:
+        return ()
+    if not enabled():
+        raise CheckError(f"surfaces is experimental and off. Set {FLAG}=1 to use it.")
+    if not isinstance(value, list) or not value:
+        raise CheckError("surfaces must list at least one surface, such as [{surface: widget, expect: [...]}]")
+    if len(value) > LIMIT:
+        raise CheckError(f"surfaces has more than {LIMIT} entries")
+    return tuple(_one(index, item, base_dir) for index, item in enumerate(value))
+
+
+def to_dict(surfaces):
+    """The file shape of ``surfaces``, as ``parse`` reads it."""
+    out = []
+    for surface in surfaces:
+        item = {"surface": surface.kind, **({"name": surface.name} if surface.name else {}), **surface.params}
+        if surface.expect:
+            item["expect"] = [assertion.to_dict() for assertion in surface.expect]
+        if surface.then:
+            item["then"] = [assertion.to_dict() for assertion in surface.then]
+        out.append(item)
+    return out

mobile_agent/verify/system_surfaces/stage.py

@@ -0,0 +1,138 @@
+"""The device side of a surface: WebDriverAgent gestures and reads on a simulator, with nothing retried after an
+unknown outcome."""
+
+import time
+
+from ..assertions import evaluate_on, folded
+from ..tree import read_tree
+from ..verdict import CouldntRun
+
+# WDA reads the app it was told is active while that app runs, even under Control Center or the Lock Screen, and the
+# run names the app under test (drivers.py). A name no app has makes WDA read the app at its detection point, a
+# system overlay included (measured 26 Oct 2026, iOS 26.4 simulator, WDA 16.12.10).
+IN_FRONT = "auto"
+READ_POLL = .5
+TAP_MS = 40
+HOLD_MS = 1200
+DRAG_MS = 350
+
+
+class SurfaceMiss(Exception):
+    """The surface couldn't be reached or didn't show; the check fails with this sentence and goes on."""
+
+
+class Stage:
+    """One simulator's screen, driven from outside the app under test. Every call is logged before it is sent."""
+
+    def __init__(self, driver, *, log, sleep=time.sleep, clock=time.monotonic):
+        self.driver, self._log, self.sleep, self.clock = driver, log, sleep, clock
+        self.size = (0.0, 0.0)
+        self.shot = None    # called with no arguments when a settle ends: the frame of the surface as it stood
+
+    def act(self, what, method, path, body=None, timeout=20):
+        """One action. An answer that never came is an unknown outcome: the run stops and nothing is sent again."""
+        self._log(f"surface: {what}")
+        try:
+            return self.driver.call(method, path, body, timeout)
+        except Exception as error:
+            raise CouldntRun("unknown_outcome",
+                             f"WebDriverAgent didn't confirm whether this happened: {what} ({type(error).__name__}).",
+                             "Look at the simulator before starting another run; Mobster didn't send it again.") \
+                from None
+
+    def follow_the_front(self):
+        """Reads come from whatever is in front until ``activate`` names an app again."""
+        self.act("read whatever is in front", "POST", "/appium/settings",
+                 {"settings": {"defaultActiveApplication": IN_FRONT}})
+
+    def read(self):
+        """The accessibility tree of whatever is in front, the Home Screen and Lock Screen included."""
+        try:
+            tree = read_tree(self.driver, pause=self.sleep)
+        except Exception as error:
+            raise CouldntRun("wda", f"WebDriverAgent stopped answering while a surface was read "
+                                    f"({type(error).__name__}).", "Run `mobster sim doctor --fix`, then try again.") \
+                from None
+        self.size = tree.size
+        return tree
+
+    def settle(self, assertions, timeout=8):
+        """Read until every assertion holds or ``timeout`` passes: (results, tree) from the last read."""
+        deadline = self.clock() + timeout
+        while True:
+            tree = self.read()
+            results = evaluate_on(assertions, tree)
+            if all(result.ok for result in results) or self.clock() >= deadline:
+                if self.shot is not None:
+                    self.shot()
+                return results, tree
+            self.sleep(READ_POLL)
+
+    def find(self, tree, *needles):
+        """The first shown node whose label or identifier contains one of ``needles``, ignoring case."""
+        wanted = [folded(needle) for needle in needles]
+        for node in tree.shown():
+            text = (folded(node.label), folded(node.identifier))
+            if any(needle and needle in part for needle in wanted for part in text):
+                return node
+        return None
+
+    def wait_for(self, needles, what, timeout=6, selector=None):
+        """The node for ``needles`` (or ``selector``) once it shows; SurfaceMiss when it never does."""
+        deadline = self.clock() + timeout
+        while True:
+            tree = self.read()
+            node = (next(iter(tree.select(selector)), None) if selector is not None
+                    else self.find(tree, *([needles] if isinstance(needles, str) else needles)))
+            if node is not None:
+                return node
+            if self.clock() >= deadline:
+                raise SurfaceMiss(f"{what} didn't show; the screen had {self._seen(tree)}")
+            self.sleep(READ_POLL)
+
+    @staticmethod
+    def _seen(tree):
+        labels = [node.label for node in tree.shown() if node.label.strip()][:6]
+        return ", ".join(f'"{label[:40]}"' for label in labels) or "no labelled elements"
+
+    def tap_node(self, node, what):
+        x, y, w, h = node.rect
+        self.tap(x + w / 2, y + h / 2, what)
+
+    def tap(self, x, y, what):
+        self._pointer(f"tap {what}", [{"type": "pointerMove", "duration": 0, "x": round(x), "y": round(y)},
+                                      {"type": "pointerDown"}, {"type": "pause", "duration": TAP_MS},
+                                      {"type": "pointerUp"}])
+
+    def hold(self, x, y, what):
+        self._pointer(f"press and hold {what}", [{"type": "pointerMove", "duration": 0, "x": round(x), "y": round(y)},
+                                                 {"type": "pointerDown"}, {"type": "pause", "duration": HOLD_MS},
+                                                 {"type": "pointerUp"}])
+
+    def drag(self, start, end, what):
+        self._pointer(f"swipe {what}", [{"type": "pointerMove", "duration": 0, "x": round(start[0]),
+                                         "y": round(start[1])}, {"type": "pointerDown"},
+                                        {"type": "pointerMove", "duration": DRAG_MS, "x": round(end[0]),
+                                         "y": round(end[1])}, {"type": "pointerUp"}])
+
+    def _pointer(self, what, steps):
+        self.act(what, "POST", "/actions", {"actions": [{"type": "pointer", "id": "finger",
+                                                         "parameters": {"pointerType": "touch"}, "actions": steps}]})
+
+    def home(self):
+        self.act("press Home", "POST", "/wda/pressButton", {"name": "home"})
+
+    def lock(self):
+        self.act("lock the simulator", "POST", "/wda/lock")
+
+    def unlock(self):
+        self.act("unlock the simulator", "POST", "/wda/unlock")
+
+    def type(self, text):
+        self.act("type into the search field", "POST", "/wda/keys", {"value": list(text)})
+
+    def siri(self, phrase):
+        self.act("ask Siri", "POST", "/wda/siri/activate", {"text": phrase})
+
+    def activate(self, bundle):
+        self.act(f"bring {bundle} forward", "POST", "/wda/apps/activate", {"bundleId": bundle})

mobile_agent/verify/system_surfaces/surfaces.py

@@ -0,0 +1,121 @@
+"""One driver per system surface. Each leaves the surface up, reads it, and returns (results, tree); ``pick`` and
+``then`` are handled once, by ``play``.
+
+The labels these drivers look for (``Edit``, ``Add Widget``, ``Done``) are the strings iOS 26 shows in English; a
+simulator in another language needs the same strings in its own."""
+
+from urllib.parse import quote, urlencode
+
+from ..assertions import parse_selector
+from .stage import SurfaceMiss
+
+ICON_ROLES = frozenset({"Icon", "Button", "Cell"})
+SEARCH_FIELD = parse_selector({"role": "field"})
+# A press and hold on the Home Screen opens edit mode with an Edit button (iOS 26.4) or a menu with Edit Home Screen;
+# Edit's menu and the widget's page both say Add Widget. Selectors, so an icon named like them is never tapped.
+EDIT_HOME = parse_selector({"label": "/^Edit( Home Screen)?$/"})
+ADD_WIDGET = parse_selector({"label": "/^\\W*Add Widget$/", "role": "button"})
+# iPhone Control Center opens from the top right; Spotlight from a swipe down on the Home Screen's middle.
+CONTROL_CENTER_X = 25
+HOME_ROWS = (.25, .75, .03)
+
+
+def empty_point(tree):
+    """A point on the Home Screen that holds no icon or button: where a press and hold opens its edit menu."""
+    width, height = tree.size
+    covered = [node.rect for node in tree.shown() if node.role in ICON_ROLES]
+    step = HOME_ROWS[2]
+    row = HOME_ROWS[0]
+    while row <= HOME_ROWS[1]:
+        for column in (.5, .15, .85):
+            x, y = width * column, height * row
+            if not any(rx <= x <= rx + rw and ry <= y <= ry + rh for rx, ry, rw, rh in covered):
+                return x, y
+        row += step
+    return None
+
+
+def intent(stage, surface, ctx):
+    """A shortcut that runs the app's App Intent (``shortcuts://run-shortcut``), or a phrase said to Siri."""
+    params = surface.params
+    if "siri" in params:
+        stage.siri(params["siri"])
+    else:
+        given = {"input": "text", "text": params["input"]} if "input" in params else {}
+        query = {"name": params["shortcut"], **given}
+        # %20, not +: Shortcuts reads a + in the name as a +, and finds no shortcut (iOS 26.4 simulator, 26 Oct 2026)
+        ctx.open_url("shortcuts://run-shortcut?" + urlencode(query, quote_via=quote))
+    return stage.settle(surface.expect)
+
+
+def widget(stage, surface, ctx):
+    """The Home Screen, after adding the app's widget from the gallery when ``add`` names the app."""
+    stage.home()
+    if "add" in surface.params:
+        _add_widget(stage, surface.params["add"])
+    return stage.settle(surface.expect)
+
+
+def _add_widget(stage, app):
+    point = empty_point(stage.read())
+    if point is None:
+        raise SurfaceMiss("the Home Screen has no empty spot to press and hold; clear a row of icons")
+    stage.hold(*point, "an empty spot on the Home Screen")
+    stage.tap_node(stage.wait_for(None, "the Home Screen's Edit button", selector=EDIT_HOME), "Edit")
+    stage.tap_node(stage.wait_for(None, "Add Widget in the Edit menu", selector=ADD_WIDGET), "Add Widget")
+    stage.tap_node(stage.wait_for(None, "the widget search field", selector=SEARCH_FIELD), "the search field")
+    stage.type(app)
+    listed = parse_selector({"label": app, "role": "cell"})   # not the app's own icon behind the gallery
+    stage.tap_node(stage.wait_for(None, f"{app} in the widget gallery", selector=listed), app)
+    stage.tap_node(stage.wait_for(None, f"the Add Widget button for {app}", selector=ADD_WIDGET), "Add Widget")
+    stage.tap_node(stage.wait_for("Done", "the Done button"), "Done")
+
+
+def live_activity(stage, surface, ctx):
+    """A Live Activity the app started, on the Lock Screen or in the Dynamic Island."""
+    if surface.params.get("where", "dynamic_island") == "lock_screen":
+        stage.lock()
+        try:
+            return stage.settle(surface.expect)
+        finally:
+            stage.unlock()
+    stage.home()
+    if surface.params.get("expanded"):
+        stage.hold(stage.read().size[0] / 2, 20, "the Dynamic Island")
+    return stage.settle(surface.expect)
+
+
+def control_center(stage, surface, ctx):
+    width, height = stage.read().size
+    stage.drag((width - CONTROL_CENTER_X, 3), (width - CONTROL_CENTER_X, height * .6), "down into Control Center")
+    return stage.settle(surface.expect)
+
+
+def app_clip(stage, surface, ctx):
+    """The App Clip, launched the way Xcode's scheme does: with its invocation URL in ``_XCAppClipURL``."""
+    params = surface.params
+    if "path" in params:
+        ctx.install(params["path"])
+    ctx.launch(params["bundle"], {"_XCAppClipURL": params["url"]})
+    stage.activate(params["bundle"])
+    return stage.settle(surface.expect)
+
+
+def spotlight(stage, surface, ctx):
+    stage.home()
+    width, height = stage.read().size
+    stage.drag((width / 2, height * .35), (width / 2, height * .75), "down on the Home Screen")
+    stage.tap_node(stage.wait_for(None, "the Spotlight search field", selector=SEARCH_FIELD), "the search field")
+    stage.type(surface.params["query"])
+    return stage.settle(surface.expect)
+
+
+def share_sheet(stage, surface, ctx):
+    """The app's own control opens the share sheet; ``expect`` reads the sheet."""
+    stage.tap_node(stage.wait_for(None, f"the control that opens the share sheet ({surface.open.render()})",
+                                  selector=surface.open), "the share control")
+    return stage.settle(surface.expect)
+
+
+DRIVERS = {"intent": intent, "widget": widget, "live_activity": live_activity, "control_center": control_center,
+           "app_clip": app_clip, "spotlight": spotlight, "share_sheet": share_sheet}