@widgex/wgx 0.0.0-stage → 0.4.2

package/python/xactor/api.py

@@ -0,0 +1,882 @@
+"""ElementaryAPI -- Layer 1.
+
+The elementary set of interactions an agent composes to drive a website. It is
+deliberately small: everything here either *locates* something or *acts* on it,
+and the two are separate verbs because the agent, not Layer 0, decides which
+candidate was meant.
+
+## The three layers, and what each is for
+
+**Layer 0** (TypeScript) receives serial actions whose intent is already
+resolved. It searches when a descriptor asks it to, executes with humanised
+input, and reports. It never chooses between close candidates. *An agent should
+never need to understand Layer 0 to drive a website.*
+
+**Layer 1** is this file. It is what the agent composes to turn a general
+intuition about identifiable features -- "there is a button that says something
+like Create, inside the dialog" -- into a concrete reference. The vocabulary
+here must match how Layer 0 resolves, or the agent would be reading one model
+and acting through another.
+
+**Layer 2** (widgets) caches those compositions into declared transitions, so a
+modelled site can be driven to an objective in a single pass.
+
+## Load a chain; stay out of the loop
+
+Actions queue. They do not need to be awaited individually, and awaiting each
+one is the habit this design exists to break::
+
+    api.click(api.find(role="button", like="create token"))
+    api.type_text(api.find(role="textbox", right_of="Name"), "ci-deploy")
+    api.click(api.find(role="button", text_exact="Create", under='dialog"Create Token"'))
+    report = await api.drain()
+
+One report comes back describing every step: what it resolved to, whether it
+worked, and what changed on the page. If step 3 cannot find its target, steps
+after it are *skipped rather than attempted* -- the page is no longer in the
+state the rest was written against -- and the report says so, with the
+candidates that tied.
+
+## Time is bounded
+
+Two ceilings, so a wedged page cannot swallow a run:
+
+- **10s per action**, covering resolving, waiting for the target, and doing the
+  thing. An action past it reports ``timeout`` and *stops touching the page*.
+- **30s for the whole chain**. Past that, actions not yet attempted report
+  ``budget_exhausted`` rather than running.
+
+Neither is a target. A click is around 300ms and a twelve-step chain a few
+seconds; these only fire when something is genuinely stuck.
+
+**Typing is exempt from both, and you do not size it.** A ``type_text`` sets its
+own ceiling from the string you gave it and the speed it will be typed at --
+about 70ms a character, divided by ``hfactor``, doubled -- and adds that to the
+chain's budget, so a form of long fields cannot exhaust it. A paragraph at
+``hfactor`` 1 simply takes the half-minute it takes -- and a quarter of that at
+``hfactor`` 4, because higher is faster.
+
+So a ``timeout`` on a type is never "the string was long": the allowance already
+knew the length. It means the field is not taking the keystrokes. Do not raise
+``timeout_ms`` at it -- read the message, then ``api.wait_stable()``.
+
+    type_text(field, essay)                      # no timeout_ms; it sizes itself
+    click(btn, batch_ms=60_000)                  # a deliberately long chain
+
+## Newlines are the Enter key
+
+Put ``\n`` in the text and it is typed as a real Enter press, not as a
+character: keyCode 13, ``code`` ``Enter``, in the page's own input pipeline.
+``\r\n`` is one press, not two.
+
+Which means it does what Enter does *in that field*. In a textarea or a rich
+editor it breaks the line; in a single-line input, or a chat composer bound to
+send, it submits. If the field sends on Enter and you want a line break, type
+the lines separately and press the shifted form between them::
+
+    type_text(box, "first line")
+    press("Shift+Enter", box)
+    type_text(box, "second line")
+
+## Referring to things
+
+An element is named by a **uid** (short, content-derived, e.g. ``e7f3a1``) or by
+a **path** through the page's structure::
+
+    main/table/row"prod-key"/button"Delete"
+    dialog"Create Token"/button"Create"
+    form#login/textbox"Username"
+
+Both resolve. A path is an assertion about the page as it is now; a uid is a
+memory of something observed. Neither is stamped into the page, so a stale
+reference matches nothing or matches several -- it can never quietly resolve to
+the wrong element.
+
+The ``xh_N`` ids from the previous engine are gone and raise if used.
+"""
+
+import asyncio
+import sys
+from typing import Any
+
+from . import bridge
+
+
+def _dbg(msg: str) -> None:
+    """Write debug output to stderr, where it cannot corrupt the JSON-RPC wire."""
+    print(f"[xactor:api] {msg}", file=sys.stderr, flush=True)
+
+
+class Ref:
+    """A reference to an element, or a description of how to find one.
+
+    Returned by :meth:`find` and :meth:`one`, and accepted anywhere an action
+    wants a target. It also carries what Layer 0 observed -- the text, the box,
+    the declared events -- so the agent can decide without a second call.
+    """
+
+    __slots__ = ("uid", "path", "role", "text", "box", "center", "events",
+                 "value", "state", "score", "in_view")
+
+    def __init__(self, data: dict[str, Any]) -> None:
+        self.uid = data.get("uid")
+        self.path = data.get("path")
+        self.role = data.get("role", "")
+        self.text = data.get("text", "")
+        self.box = data.get("box")
+        self.center = data.get("center")
+        self.events = data.get("events", [])
+        self.value = data.get("value")
+        self.state = data.get("state", {})
+        self.score = data.get("score")
+        self.in_view = data.get("inView", True)
+
+    @property
+    def disabled(self) -> bool:
+        return bool(self.state.get("disabled"))
+
+    def as_target(self) -> str:
+        """How this crosses to Layer 0.
+
+        The uid *and* the path when both are known: the uid is what identifies
+        the element, and the path lets Layer 0 notice it has moved somewhere
+        that changes what a click would mean.
+        """
+        if self.uid and self.path:
+            return f"{self.uid}@{self.path}"
+        return self.uid or self.path or ""
+
+    def __repr__(self) -> str:
+        bits = [self.role or "?"]
+        if self.text:
+            bits.append(repr(self.text))
+        if self.score is not None:
+            bits.append(f"score={self.score:.2f}")
+        return f"<Ref {' '.join(bits)} {self.path or self.uid}>"
+
+
+def _target(t: Any) -> Any:
+    """Normalise whatever an action was given into something Layer 0 accepts."""
+    if isinstance(t, Ref):
+        return t.as_target()
+    if isinstance(t, FindSpec):
+        return t.spec
+    if isinstance(t, dict):
+        return t
+    return str(t)
+
+
+class FindSpec:
+    """A search deferred until the queue reaches the action holding it.
+
+    This is what makes ``click(find(...))`` work on something that does not
+    exist yet -- the dialog button an earlier action in the same chain is about
+    to bring into being. Nothing is evaluated when you build it.
+    """
+
+    __slots__ = ("spec",)
+
+    def __init__(self, spec: dict[str, Any]) -> None:
+        self.spec = spec
+
+    def __repr__(self) -> str:
+        return f"<FindSpec {self.spec}>"
+
+
+def _spec(
+    role: str | list[str] | None = None,
+    like: str | None = None,
+    text_exact: str | None = None,
+    under: Any = None,
+    near: Any = None,
+    above: Any = None,
+    below: Any = None,
+    left_of: Any = None,
+    right_of: Any = None,
+    in_row: Any = None,
+    in_section: Any = None,
+    attr: dict[str, str] | None = None,
+    state: dict[str, bool] | None = None,
+    in_view: bool | None = None,
+    interactive: bool | None = None,
+    include_inert: bool | None = None,
+    limit: int | None = None,
+    margin: float | None = None,
+) -> dict[str, Any]:
+    """Build the wire form of a search. Snake_case in, camelCase out."""
+    out: dict[str, Any] = {}
+    if role is not None:
+        out["role"] = role
+    if like is not None:
+        out["like"] = like
+    if text_exact is not None:
+        out["textExact"] = text_exact
+    for key, val in (
+        ("under", under), ("near", near), ("above", above), ("below", below),
+        ("leftOf", left_of), ("rightOf", right_of),
+        ("inRow", in_row), ("inSection", in_section),
+    ):
+        if val is not None:
+            out[key] = _target(val)
+    if attr is not None:
+        out["attr"] = attr
+    if state is not None:
+        out["state"] = state
+    if in_view is not None:
+        out["inView"] = in_view
+    if interactive is not None:
+        out["interactive"] = interactive
+    if include_inert is not None:
+        out["includeInert"] = include_inert
+    if limit is not None:
+        out["limit"] = limit
+    if margin is not None:
+        out["margin"] = margin
+    return out
+
+
+class ElementaryAPI:
+    """Layer 1. Compose these to locate things; hand the result to an action."""
+
+    #: Actions scheduled but not yet collected by :meth:`drain`.
+    _pending: "list[asyncio.Future[Any]] | None" = None
+    #: The most recently scheduled action, so the next one can follow it.
+    _tail: "asyncio.Future[Any] | None" = None
+
+    def _enqueue(self, coro: "Any") -> "asyncio.Future[Any]":
+        """Schedule an action now and hand back something awaitable.
+
+        This is what makes ``api.click(x)`` work without ``await``.
+
+        A bare ``async def`` cannot: a coroutine nobody awaits is never
+        scheduled, so it simply does not happen — silently, apart from a
+        RuntimeWarning nobody sees in a webview. The docstrings below have
+        always promised that actions queue and ``drain()`` collects them, and
+        that promise needs a task rather than a coroutine behind it.
+
+        Chained rather than fired in parallel. Actions are ordered by
+        construction — you clear a field *then* click Save — and letting the
+        event loop interleave two of them would reorder the page's input for
+        no gain, because the queue that matters is the host's and it is fed in
+        receipt order.
+
+        Awaiting the returned future gives that action's own record, exactly as
+        before; ignoring it leaves the work scheduled and lets ``drain()``
+        report on it.
+        """
+        if self._pending is None:
+            self._pending = []
+        prev = self._tail
+
+        async def _run() -> Any:
+            if prev is not None:
+                # A failed predecessor must not cancel what follows here: Layer
+                # 0 decides what a failure does to the rest of the chain and
+                # reports it as `skipped`. This only enforces order.
+                try:
+                    await prev
+                except Exception:
+                    pass
+            return await coro
+
+        task = asyncio.ensure_future(_run())
+        self._pending.append(task)
+        self._tail = task
+        return task
+
+    # ── Locating ──────────────────────────────────────────────────────
+
+    def find(self, **kw: Any) -> FindSpec:
+        """Describe a search, without running it.
+
+        Use this **inside an action** to defer the lookup to dispatch time::
+
+            api.click(api.find(role="button", like="create token"))
+
+        That is the form to reach for by default: it costs no round trip when
+        you build it, and it resolves against the page as it will be when the
+        click actually happens rather than as it is now.
+
+        To *see* the candidates instead, await :meth:`search`.
+
+        Args:
+            role: An ARIA role, or a list of them. Same vocabulary the paths
+                use -- ``button``, ``link``, ``textbox``, ``row``, ``dialog``.
+            like: Approximate text. Ranked, not filtered.
+            text_exact: Exact text, after normalisation.
+            under: Restrict to a subtree, by ref or path.
+            near / above / below / left_of / right_of: Geometric relations. The
+                anchor may be a ref, a path, or just the visible text of a label
+                -- ``right_of="Name"`` is how you reach the field beside a
+                caption that is not itself addressable.
+            in_row / in_section: Containment, for tables and landmarks.
+            state: e.g. ``{"enabled": True}``.
+            in_view: Default True. Off-screen matches are excluded and counted.
+            margin: How decisive the ranking must be before Layer 0 will act.
+                ``0`` takes the top rank; ``1`` acts only if nothing else
+                matched at all. Default 0.15.
+        """
+        return FindSpec(_spec(**kw))
+
+    async def search(self, **kw: Any) -> list[Ref]:
+        """Run a search now and return the ranked candidates.
+
+        Zero results is an ordinary answer, not an error -- "I cannot find it"
+        is the normal case on a graphical UI, and it is information.
+
+        Each :class:`Ref` carries its ``score``. When the top two are close,
+        that is the page telling you the description was not specific enough::
+
+            cands = await api.search(role="button", like="create")
+            # [<Ref button 'Create Token' score=0.90>,
+            #  <Ref button 'Create Team'  score=0.90>]
+        """
+        result = await bridge.call("find", find=_spec(**kw))
+        if isinstance(result, dict) and result.get("error"):
+            _dbg(f"search error: {result}")
+            return []
+        nodes = (result or {}).get("nodes") or []
+        return [Ref(n) for n in nodes]
+
+    async def one(self, **kw: Any) -> Ref:
+        """Exactly one match, or raise with the candidates attached.
+
+        Use when you believe the description is unambiguous and want to be told
+        immediately if it is not. The exception body lists what tied, which is
+        the refinement hint for your next attempt.
+        """
+        result = await bridge.call("one", find=_spec(**kw))
+        if isinstance(result, dict) and result.get("error"):
+            cands = result.get("candidates") or []
+            detail = "\n".join(
+                f"  {c.get('score', 0):.2f}  {c.get('path') or c.get('uid')}"
+                f"  {c.get('text', '')!r}"
+                for c in cands
+            )
+            raise LookupError(
+                f"{result['error']}: no single match for {_spec(**kw)}"
+                + (f"\ncandidates:\n{detail}" if detail else "")
+            )
+        return Ref(result)
+
+    async def outline(self, under: Any = None, depth: int = 2) -> dict[str, Any]:
+        """The shape of the page -- roles and names, no geometry.
+
+        The cheapest way to orient. Read this before reaching for a screenshot;
+        a screenshot puts you back in the loop for every lookup, which is the
+        cost this whole design exists to avoid.
+        """
+        return await bridge.call("outline", under=_target(under) if under else None, depth=depth)
+
+    async def snapshot(self, **kw: Any) -> dict[str, Any]:
+        """The interactive tree, filtered.
+
+        Conservative by default: in-viewport, interactive elements only, with
+        everything omitted reported as a count so you always know what you are
+        not being shown.
+        """
+        return await bridge.call("tag", **_spec(**kw))
+
+    async def digest(self) -> dict[str, Any]:
+        """A cheap rollup of the page, for "did anything change?"."""
+        return await bridge.call("digest")
+
+    # ── Acting ────────────────────────────────────────────────────────
+    #
+    # These queue. Awaiting one is allowed and gives you its record; not
+    # awaiting is the point, and `drain()` collects the lot.
+    #
+    # They return a scheduled task rather than being `async def`, which is what
+    # makes the second half of that true — see `_enqueue`. `await api.click(x)`
+    # behaves exactly as it always has.
+
+    def click(self, target: Any, **kw: Any) -> "asyncio.Future[Any]":
+        """Click something. Returns the record of what happened."""
+        return self._enqueue(bridge.call("click", selector=_target(target), **_action_kw(kw)))
+
+    def double_click(self, target: Any, **kw: Any) -> "asyncio.Future[Any]":
+        """Double-click something.
+
+        The same verb as :meth:`click` with a count, which is what the DOM says
+        it is: the two presses land back-to-back at one point, so the page sees
+        `dblclick` rather than two separate clicks.
+
+        Reach for it when single and double click on the same element mean
+        different things -- opening versus renaming, a chat versus a card. If
+        the interface offers a button for what the double click does, prefer
+        the button: it is what a keyboard user has to press anyway.
+        """
+        return self._enqueue(
+            bridge.call("click", selector=_target(target), click_count=2, **_action_kw(kw)))
+
+    def type_text(self, target: Any, text: str, **kw: Any) -> "asyncio.Future[Any]":
+        """Type into a field, appending to whatever is there.
+
+        ``\\n`` is typed as a real Enter press -- a line break in a textarea, a
+        send in anything bound to send. The action sizes its own timeout from
+        the length of ``text``, so do not pass ``timeout_ms``.
+        """
+        return self._enqueue(
+            bridge.call("type", selector=_target(target), text=text, **_action_kw(kw)))
+
+    def clear_and_type(self, target: Any, text: str, **kw: Any) -> "asyncio.Future[Any]":
+        """Replace a field's contents. Same newline and timeout rules as
+        :meth:`type_text`."""
+        return self._enqueue(
+            bridge.call("clear_type", selector=_target(target), text=text, **_action_kw(kw)))
+
+    def hover(self, target: Any, **kw: Any) -> "asyncio.Future[Any]":
+        return self._enqueue(bridge.call("hover", selector=_target(target), **_action_kw(kw)))
+
+    def scroll_to(self, target: Any, **kw: Any) -> "asyncio.Future[Any]":
+        return self._enqueue(bridge.call("scroll_to", selector=_target(target), **_action_kw(kw)))
+
+    def select(self, target: Any, value: str | None = None,
+               label: str | None = None, **kw: Any) -> "asyncio.Future[Any]":
+        """Choose an option in a native ``<select>``.
+
+        A custom ARIA combobox is a different thing and this refuses it rather
+        than guessing: click the trigger, then click the option scoped to the
+        listbox it opens.
+        """
+        return self._enqueue(bridge.call("select", selector=_target(target),
+                                         value=value, label=label, **_action_kw(kw)))
+
+    def focus(self, target: Any, **kw: Any) -> "asyncio.Future[Any]":
+        """Put keyboard focus on something.
+
+        The other half of keyboard navigation. :meth:`press` types at whatever
+        is focused; this is how you decide what that is.
+
+        Reach for it when a control cannot be clicked. A custom combobox --
+        react-select and everything shaped like it -- hides a 1-2px input under
+        a styled div, so a click is correctly refused as *covered*, and the
+        wrapper's class is a build hash not worth writing down. The keyboard is
+        the way in, and it is also how a person would do it::
+
+            api.focus('#Project--permission')
+            api.press('ArrowDown', times=2)   # open, then move
+            api.press('Enter')                # commit
+
+        Reports ``not_interactable`` rather than ``ok`` when the element
+        refuses focus -- a disabled control, something inert, a div with no
+        tabindex. Assuming it took would send the next ``press`` to whatever
+        was focused before.
+        """
+        return self._enqueue(bridge.call("focus", selector=_target(target), **_action_kw(kw)))
+
+    def press(self, keys: str, target: Any = None, times: int | None = None,
+              **kw: Any) -> "asyncio.Future[Any]":
+        """Press a key or chord, e.g. ``"Enter"`` or ``"Control+a"``.
+
+        Args:
+            keys: The chord. Modifiers join with ``+``: ``"Control+a"``.
+            target: Optional. Focus this first, so one step can mean "press
+                Enter *in this field*" rather than "press Enter at whatever the
+                page last focused".
+            times: Repeat the chord. For walking a listbox without writing the
+                same step four times. Capped at 50 -- a runaway repeat is a
+                held key the page cannot recover from.
+        """
+        extra: dict[str, Any] = {}
+        if target is not None:
+            extra["selector"] = _target(target)
+        if times is not None:
+            extra["times"] = times
+        return self._enqueue(bridge.call("press", keys=keys, **extra, **_action_kw(kw)))
+
+    async def navigate(self, url: str) -> dict[str, Any]:
+        # Not an `_api_method`, so it never passed the seal check `drive` does:
+        # `navigate('file:///…/secret')` and then `outline()` read a sealed
+        # file straight back. The browser refuses a sealed `file://` load on
+        # its own too (see `sealedFileUrl` in the TS browser layer); this is
+        # the earlier, clearer refusal.
+        from . import seals
+        meta = bridge.exec_meta.get() or {}
+        seals.check_call("navigate", {"url": url}, meta.get("modelId"))
+        return await bridge.call("navigate", url=url)
+
+    # ── Guiding a person through the app ────────────────────────────
+    #
+    # Ringing a control and putting a sentence beside it are ways of driving a
+    # surface, like clicking and typing, so they are verbs here rather than a
+    # feature somewhere above. The agent guides live: ring something, see
+    # whether it resolved, decide what to say next. Nothing is predicted in
+    # advance, so nothing has to be validated in advance.
+    #
+    # Awaited rather than queued. A chain of clicks is worth batching because
+    # nobody is watching it; these exist precisely because somebody is, and each
+    # one is a thing the agent should see the result of before it says the next
+    # sentence.
+
+    async def highlight(self, target: Any = None, label: str | None = None) -> dict[str, Any]:
+        """Ring a control in the app. Pass nothing to take the ring down.
+
+        Drawn inside the page, so it appears whether the app is in its own
+        window or being mirrored — a mirror is a picture of the page, and the
+        ring is part of the page.
+
+        Returns ``{status, box}`` when it drew. When it could not, the reason
+        comes back rather than raising: ``that description matches more than one
+        control`` is the agent's to narrow, and ``that control is not on this
+        screen`` is usually the app being somewhere else, which is worth saying
+        to the user rather than failing on.
+        """
+        if target is None:
+            return await bridge.call("highlight", selector=None)
+        return await bridge.call(
+            "highlight", selector=_target(target), **({"label": label} if label else {}),
+        )
+
+    async def instruct(
+        self,
+        text: str | None,
+        target: Any = None,
+        *,
+        expect: str | None = None,
+        title: str = "",
+        step: int | None = None,
+        total: int | None = None,
+    ) -> dict[str, Any]:
+        """Put a sentence in the app, beside a control when you name one.
+
+        With a ``target`` the card is placed against that control with a pointer
+        and the control is ringed; without one it takes a corner, which is right
+        for "watch what happens next" and wrong for anything naming a button.
+
+        Pass ``text=None`` to take it down.
+
+        Keep it short and imperative — it sits beside a live app and is skimmed,
+        not read. Name the control in the words as well as ringing it: the ring
+        is dropped whenever the geometry cannot be proven, and a sentence that
+        leans on it breaks exactly when the safety net fires.
+
+        ``step``/``total`` are optional and only draw a counter. Omit them for a
+        single instruction; pass them when you are walking somebody through
+        several and they will want to know how far along they are.
+        """
+        kw: dict[str, Any] = {"text": text, "title": title}
+        if target is not None:
+            kw["selector"] = _target(target)
+        if expect is not None:
+            kw["expect"] = expect
+        if step is not None:
+            kw["step"] = step
+        if total is not None:
+            kw["total"] = total
+        return await bridge.call("instruct", **kw)
+
+    async def reply(self, text: str) -> dict[str, Any]:
+        """Answer a question without taking the step away.
+
+        For what comes back as ``asked``. The instruction, the ring and the
+        counter all stay exactly as they were and the answer goes underneath —
+        a word with somebody about the step they are on, rather than a new step.
+
+        Do not use :meth:`instruct` for this. That call *is* a new step: it
+        moves the ring, resets the counter and replaces the words, so answering
+        with it takes away the very sentence the question was about.
+
+        Then call :meth:`await_user` again on the same target to hand the step
+        back to them.
+        """
+        return await bridge.call("reply", text=text)
+
+    async def await_user(
+        self, target: Any = None, timeout_seconds: int = 300
+    ) -> dict[str, Any]:
+        """Wait for the person to do something, and say what they did.
+
+        One wait, five answers, because a person being guided has more than one
+        thing they might do::
+
+            {"clicked": True}                they clicked the control you rang
+            {"advanced": True}               they pressed Next
+            {"reported": True}               they marked what is wrong and sent it
+            {"asked": "why this one?"}       they typed a question
+            {"stopped": True}                they ended it — Finish, or the chat
+            {"clicked": False, "reason": …}  nothing, for the whole window
+
+        ``reported`` always carries ``annotations`` and means they stopped to
+        say something is wrong rather than doing what the step asked. Deal with
+        what is marked before writing another step.
+
+        Any of them may also carry ``annotations``: boxes somebody drew on the
+        app with "Mark what is wrong", each with a note and a picture of the
+        screen as it was when they wrote it. **That is the point of showing
+        somebody something rather than asking them.** A demo walked end to end
+        can still be a demo of six broken screens, so deal with what they
+        marked before you claim anything works. Regions are normalised 0-1, so
+        they survive the window being resized.
+
+        ``stopped`` is not a failure and not something to argue with. Take the
+        card down with ``instruct(None)``, say what you were about to show in a
+        sentence, and stop.
+
+        The tour also raises a row in the chat and the Needs-you queue for as
+        long as it runs, so somebody looking at neither the app window nor this
+        conversation can still see that a demo is waiting on them. It closes
+        when you call ``instruct(None)``. Answering *there* settles this wait —
+        whichever surface they reach for wins.
+
+        A press never reaches this side in a real window — the app handles it —
+        so it is reported out of the page and tested the way a mirrored click
+        is: both ends inside the control, barely any travel between them, so a
+        press that slides off stays the cancelled click it looks like.
+
+        ``target`` is optional. Omit it for a step with nothing to click ("read
+        this, then carry on"); Next and the question box are still there.
+
+        The timeout is **not an error**. Somebody who did something else is not
+        a failure, and noticing it is how you say something useful next.
+
+        Answer a question with :meth:`reply`, then wait again on the same
+        target. :meth:`instruct` *is* a new step — it moves the ring, resets the
+        counter and replaces the words — so answering with it takes away the
+        sentence the question was about. Reach for it only when the answer
+        genuinely lives somewhere else; a question is allowed to take the tour
+        off course, and ``title="detour"`` is how you say so.
+        """
+        return await bridge.call(
+            "await_user",
+            selector=_target(target) if target is not None else None,
+            timeout_ms=timeout_seconds * 1000,
+        )
+
+    async def drain(self) -> dict[str, Any]:
+        """Wait for every queued action and return one report for the chain.
+
+        The report names each action, what it resolved to, whether it worked,
+        and what changed. A failure stops the chain -- the remainder is reported
+        as ``skipped`` rather than attempted.
+        """
+        # Settle anything scheduled but not awaited before asking the host for
+        # the report. Without this, `drain()` races the actions it is meant to
+        # be reporting on and returns `{'actions': [], 'ok': 0}` — which reads
+        # as "the chain ran and did nothing" rather than "it has not run yet".
+        pending, self._pending, self._tail = (self._pending or []), [], None
+        records: list[Any] = []
+        for task in pending:
+            try:
+                rec = await task
+                if isinstance(rec, dict):
+                    records.append(rec)
+            except Exception as err:  # noqa: BLE001 - reported as a failed action
+                _dbg(f"queued action failed: {err}")
+                records.append({"kind": "unknown", "ok": False,
+                                "outcome": "error", "error": str(err)})
+
+        host = await bridge.call("drain")
+        host = host if isinstance(host, dict) else {}
+
+        # The host's queue is empty by now, because every action's own
+        # `bridge.call` already resolved with its record — so its report counts
+        # nothing. The chain-level report the docstring promises has to be
+        # assembled from the records we collected, and the host's is kept only
+        # for the fields it alone knows (the url before/after, the elapsed ms).
+        if records and not (host.get("actions") or []):
+            host = {
+                **host,
+                "actions": records,
+                "ok": sum(1 for r in records if r.get("ok")),
+                "failed": sum(1 for r in records if not r.get("ok")),
+                "skipped": host.get("skipped", 0),
+            }
+        return host
+
+    # ── Waiting ───────────────────────────────────────────────────────
+
+    async def wait_for(self, target: Any, condition: str = "visible",
+                       timeout_ms: int | None = None) -> dict[str, Any]:
+        """Sleep until an element is there.
+
+        Rarely needed explicitly: an action already waits for its own target.
+        Reach for it when you want to wait for something you are not about to
+        touch -- a spinner to go (``condition="gone"``), or a result to appear.
+        """
+        return await bridge.call("wait_for_element", selector=_target(target),
+                                 condition=condition, timeout=timeout_ms)
+
+    async def wait_stable(self, timeout_ms: int | None = None) -> dict[str, Any]:
+        """Wait for the page to stop loading and stop changing."""
+        return await bridge.call("wait_stable", timeout=timeout_ms)
+
+    # ── DOM-level input, for pages that never paint ───────────────────
+    #
+    # `click` and `type_text` synthesise real input events, which is what makes
+    # them humanised -- and what makes them useless on a background page.
+    # Chromium does not deliver synthesised input to a document whose
+    # visibilityState is "hidden", and it does not complain either. Layer 0 now
+    # detects that and fails with `page_hidden` instead of reporting success,
+    # but these two are the way to actually do the work there.
+
+    async def dom_click(self, target: Any) -> dict[str, Any]:
+        """Click through the DOM, without synthesising input."""
+        return await bridge.call("dom_click", selector=_target(target))
+
+    async def dom_fill(self, target: Any, text: str) -> dict[str, Any]:
+        """Set a field's value so React and Angular notice."""
+        return await bridge.call("dom_fill", selector=_target(target), text=text)
+
+    async def upload(self, target: Any, paths: Any) -> dict[str, Any]:
+        """Attach file(s) from disk to an ``<input type=file>``.
+
+        Page script cannot do this, so it is a verb of its own. ``target`` may be
+        the input or the styled button / drop zone around it; ``paths`` is an
+        absolute path or a list of them. The page gets its ``change`` event as
+        if the user had picked the files in the dialog. Reports
+        ``{"error": "no_file_input"}`` when nothing file-shaped is there.
+        """
+        if isinstance(paths, (str, bytes)) or not hasattr(paths, "__iter__"):
+            paths = [paths]
+        return await bridge.call("upload", selector=_target(target), paths=[str(p) for p in paths])
+
+    # ── Reading ───────────────────────────────────────────────────────
+
+    async def evaluate(self, expr: str) -> Any:
+        """Evaluate JavaScript in the page. The escape hatch."""
+        return await bridge.call("evaluate", expr=expr)
+
+    async def get_state(self) -> dict[str, Any]:
+        """The page's URL and title. **Not** the widget's state machine.
+
+        For where you are in a loaded widget, use :meth:`here`.
+        """
+        return await bridge.call("get_state")
+
+    def _surface(self) -> Any:
+        """The `api` a widget should see — the whole one, not just this half.
+
+        Layer 1 is grafted onto the stdlib `api` as *bound* methods, so `self`
+        inside them is this ElementaryAPI rather than the object the agent
+        calls. That is harmless for a verb that only reaches `bridge`, and
+        wrong the moment one hands `self` onward: a `PageState` built from it
+        can dispatch `click` and not `request_operator_action`, so a widget
+        step that asks the user to sign in dies with "ElementaryAPI has no
+        method 'request_operator_action'" — a page verb and a shell verb
+        sitting on the same `api` and only one of them reaching a widget.
+
+        `_merged` is set by `_graft_browser_l1`. Absent in the browser-only
+        shell, where this object really is the whole surface.
+        """
+        return getattr(self, "_merged", self)
+
+    async def here(self) -> Any:
+        """Which of the loaded widget's states the page is on right now.
+
+        The same thing as ``await registry.here(api)``, reachable by looking at
+        ``api``.
+
+        That is the entire reason it exists. ``registry`` is a bare name in the
+        shell scope, so it does not appear in ``dir(api)`` — and ``dir(api)`` is
+        what a model actually does when it wants to know what it can call. A
+        session that had already loaded a widget correctly went on to invent
+        ``api.widget_action``, then tried ``api.get_state()['transitions']``,
+        then ``api.drive('create_token')``, and never once reached the machine
+        that was sitting right there.
+
+        Returns a ``PageState``. ``describe()`` lists its transitions;
+        ``execute(name, **params)`` runs one — or use :meth:`transition`.
+        """
+        from .states import StateRegistry
+        return await StateRegistry.here(self._surface())
+
+    async def transition(self, name: str, /, **params: Any) -> Any:
+        """Run one of the current state's named transitions.
+
+        Shorthand for ``(await api.here()).execute(name, **params)``, which is
+        the whole of a widget-driven task once ``use_widget`` has landed you
+        somewhere.
+
+        Returns the ``PageState`` you end up in, so a flow reads as a chain::
+
+            await api.use_widget("sentry_tokens")
+            await api.transition("create_token")
+            await api.transition("configure", token_name="ci-deploy")
+        """
+        state = await self.here()
+        return await state.execute(name, **params)
+
+    async def screenshot(self, max_width: int | None = None) -> dict[str, Any]:
+        """Capture the page as an image.
+
+        An image is *seen, not queryable*, and looking at one costs a round trip
+        through you. Prefer :meth:`outline`, :meth:`search` and the spatial
+        predicates -- ``right_of="Name"`` locates a field without a picture.
+        Use this for genuinely visual questions: layout, rendering, or
+        confirming a human did something you asked them to.
+        """
+        params: dict[str, Any] = {}
+        if max_width is not None:
+            params["max_width"] = max_width
+        return await bridge.call("screenshot", **params)
+
+    async def extract_secret(self, target: Any, env_var: str) -> dict[str, Any]:
+        """Write a revealed value to `NAME=value` in the workspace's `.env`,
+        without it passing through this layer.
+
+        It lands in the file, not in any process's environment: `api.bash`
+        sees `$env_var` only after loading it (`set -a; . ./.env; set +a`).
+        """
+        return await bridge.call("extract_secret", selector=_target(target), env_var=env_var)
+
+    async def set_hfactor(self, value: float) -> dict[str, Any]:
+        """Humanisation speed. **Higher is faster.** 1.0 is normal.
+
+        It divides every delay rather than being one, which is the bit that
+        gets read backwards: 2.0 halves the pauses and runs twice as fast;
+        0.5 doubles them and runs half as fast. To speed a script up, go up.
+
+        Per-dispatcher, so raising it for an unattended login does not leave a
+        global switch flipped for everything else.
+        """
+        return await bridge.call("set_hfactor", value=value)
+
+    # ── Withdrawn ─────────────────────────────────────────────────────
+
+    async def query(self, *_args: Any, **_kwargs: Any) -> Any:
+        """Withdrawn. Use :meth:`search` or :meth:`find`.
+
+        Kept as a refusal rather than deleted: an agent calling a method that no
+        longer exists gets an AttributeError and guesses, and its guess is
+        usually another name that is also missing.
+        """
+        raise RuntimeError(
+            "api.query() is withdrawn -- it returned a flat list with xh_ ids that "
+            "dangled on re-render.\n"
+            "  await api.search(role=..., like=...)   ranked candidates you can look at\n"
+            "  api.find(role=..., like=...)           a search deferred into an action\n"
+            "  await api.one(role=..., text_exact=...) exactly one, or the candidates"
+        )
+
+    async def hybrid_snapshot(self, *_args: Any, **_kwargs: Any) -> Any:
+        """Withdrawn. Use :meth:`snapshot` or :meth:`outline`."""
+        raise RuntimeError(
+            "api.hybrid_snapshot() is withdrawn -- it returned a flat list with no "
+            "containment, so eight identical 'Delete' buttons were indistinguishable.\n"
+            "  await api.outline()    the shape of the page, cheapest\n"
+            "  await api.snapshot()   the interactive tree, filtered"
+        )
+
+    async def query_one(self, *_args: Any, **_kwargs: Any) -> Any:
+        """Withdrawn. Use :meth:`one`."""
+        raise RuntimeError("api.query_one() is withdrawn -- use await api.one(...)")
+
+
+def _action_kw(kw: dict[str, Any]) -> dict[str, Any]:
+    """Pass through the per-action knobs, dropping anything unset.
+
+    ``timeout_ms`` is the action's whole ceiling -- resolving, waiting for its
+    target, and performing it -- not just one phase of it. ``batch_ms`` sets the
+    total for the chain and is read from whichever action opens it.
+    """
+    out: dict[str, Any] = {}
+    if kw.get("margin") is not None:
+        out["margin"] = kw["margin"]
+    if kw.get("timeout_ms") is not None:
+        out["timeout"] = kw["timeout_ms"]
+    if kw.get("batch_ms") is not None:
+        out["batch_ms"] = kw["batch_ms"]
+    if kw.get("hfactor") is not None:
+        out["hfactor"] = kw["hfactor"]
+    return out