@widgex/wgx 0.0.0-stage → 0.4.1

package/python/xactor/states/base.py

@@ -0,0 +1,523 @@
+"""Core Layer 2 classes: Observation, Step, Transition, PageState, LoadingState."""
+
+from __future__ import annotations
+
+import re
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..api import ElementaryAPI
+    from ..dom import DOMSnapshot
+
+
+class Observation:
+    """Declarative DOM data extraction.
+
+    Two modes:
+    - Structured: selector + extract (attribute name or list) → compiled to JS
+    - Raw: js expression evaluated directly
+    """
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        description: str = "",
+        js: str | None = None,
+        selector: str | None = None,
+        extract: str | list[str] | None = None,
+    ) -> None:
+        self.name = name
+        self.description = description
+        self._js = js
+        self.selector = selector
+        self.extract = extract
+
+        if js is None and selector is None:
+            raise ValueError(f"Observation '{name}' needs either 'js' or 'selector'")
+        if js is not None and selector is not None:
+            raise ValueError(f"Observation '{name}' cannot have both 'js' and 'selector'")
+        if selector is not None and re.match(r'^[a-z]+"[^"]*"', selector):
+            # `button"Create Token"` is a Layer 0 path, not CSS; interpolated
+            # into querySelector it throws a SyntaxError in the page, at run
+            # time. Refuse it where the author can still see it.
+            raise ValueError(
+                f"Observation '{name}': selector {selector!r} looks like a path "
+                f"(role\"name\"), but Observation.selector is CSS. Use a CSS "
+                f"selector, or js= with an explicit query."
+            )
+
+    def compile_js(self) -> str:
+        """Compile this observation to a JavaScript expression."""
+        if self._js is not None:
+            return self._js
+
+        sel = self.selector
+        assert sel is not None
+
+        if isinstance(self.extract, list):
+            # Multiple attributes from all matches
+            attrs = self.extract
+            props = ", ".join(
+                f"{a}: el.getAttribute('{a}') ?? el.textContent?.trim() ?? null"
+                if a == "textContent"
+                else f"{a}: el.getAttribute('{a}') ?? null"
+                for a in attrs
+            )
+            return (
+                f"Array.from(document.querySelectorAll('{sel}')).map(el => "
+                f"({{ {props} }}))"
+            )
+        elif isinstance(self.extract, str):
+            # Single attribute from first match
+            attr = self.extract
+            if attr == "textContent":
+                return f"document.querySelector('{sel}')?.textContent?.trim() ?? null"
+            return f"document.querySelector('{sel}')?.getAttribute('{attr}') ?? document.querySelector('{sel}')?.textContent?.trim() ?? null"
+        else:
+            # No extract specified — return textContent of first match
+            return f"document.querySelector('{sel}')?.textContent?.trim() ?? null"
+
+    async def run(self, api: ElementaryAPI) -> Any:
+        """Execute this observation via the bridge."""
+        js = self.compile_js()
+        return await api.evaluate(js)
+
+
+# ── Legacy target bridge ──────────────────────────────────────────────
+#
+# Widgets written against the old engine name elements the way that engine
+# resolved them: by visible text, by a bare tag, by a CSS selector. Layer 0 no
+# longer guesses -- it takes a uid or a path -- so those targets would resolve to
+# nothing.
+#
+# Rather than let ~90 steps across the shipped widgets fail one at a time, this
+# translates a legacy target into an explicit *search*. That is a deliberate
+# choice about where the guessing lives: Layer 0 stays strict, and Layer 2 opts
+# in visibly, under the same ranking and margin an agent would get.
+#
+# It is a bridge, not a destination. A rewritten widget should name paths from
+# api.search() and skip all of this.
+
+# `focus` is here because it takes a target and so needs the same legacy-target
+# translation the others do. `press` is deliberately absent: its first argument
+# is a chord, not an element, and putting it through the target bridge would
+# have "Enter" resolved as a description of something on the page.
+_HUMANISED = frozenset({
+    "click", "type_text", "clear_and_type", "hover", "scroll_to", "select",
+    "focus",
+})
+
+# What the caller is plainly aiming at, when the verb says so.
+_ROLE_FOR_VERB = {
+    "type_text": "textbox",
+    "clear_and_type": "textbox",
+    "select": "combobox",
+}
+
+_TAG_ROLE = {
+    "button": "button", "a": "link", "input": "textbox", "textarea": "textbox",
+    "select": "combobox", "table": "table", "tr": "row", "li": "listitem",
+    "ul": "list", "ol": "list", "dialog": "dialog", "form": "form", "nav": "navigation",
+}
+
+_STEP_VERB_ALIASES = {"clear_type": "clear_and_type", "type": "type_text"}
+
+_UID_RE = re.compile(r"^[0-9a-f]{6}(~\d+)?$")
+_BARE_TAG_RE = re.compile(r"^[a-z][a-z0-9-]*$")
+_ATTR_RE = re.compile(r"""^\[([\w-]+)\s*=\s*["']?([^"'\]]+)["']?\]$""")
+
+
+def _is_new_style(target: str) -> bool:
+    """A uid, or a path. Paths carry a separator, a quoted name, or a #id/@testid.
+
+    The leading-bracket test comes first and is not redundant: a CSS attribute
+    selector like ``[data-testid="x"]`` contains a double quote, which would
+    otherwise read as a path's quoted name. A real path never *starts* with a
+    bracket -- the index bracket only ever follows a role or a discriminator.
+    """
+    if target.startswith("["):
+        return False
+    return bool(
+        _UID_RE.match(target)
+        or "/" in target
+        or '"' in target
+        or target.startswith("#")
+        or target.startswith("@")
+    )
+
+
+def legacy_target(action: str, selector: Any, kwargs: dict[str, Any]) -> Any:
+    """Translate an old-style target into something Layer 0 accepts.
+
+    Only for the humanised verbs. ``dom_click``, ``dom_fill``,
+    ``wait_for_element`` and ``extract_secret`` still take CSS directly, which is
+    why the three console widgets authored against them need no translation at
+    all.
+    """
+    if action not in _HUMANISED or not isinstance(selector, str) or not selector.strip():
+        return selector
+
+    s = selector.strip()
+    if _is_new_style(s):
+        return s
+
+    spec: dict[str, Any] = {}
+    attr_match = _ATTR_RE.match(s)
+    if attr_match:
+        spec["attr"] = {attr_match.group(1): attr_match.group(2)}
+        role = _ROLE_FOR_VERB.get(action)
+        if role:
+            spec["role"] = role
+    elif _BARE_TAG_RE.match(s):
+        # A bare tag was always "the only one of these on the page".
+        spec["role"] = _TAG_ROLE.get(s, s)
+    else:
+        # Visible text. Ranked rather than matched exactly, because the old
+        # engine did a substring walk and the accessible name the new one
+        # computes is not always character-identical to it.
+        spec["like"] = s
+        role = _ROLE_FOR_VERB.get(action)
+        if role:
+            spec["role"] = role
+
+    # `container=` scoped a lookup; `under=` is the same idea by its current name.
+    container = kwargs.pop("container", None)
+    if container:
+        spec["under"] = container
+
+    return spec
+
+
+def _search_kw(spec: dict[str, Any]) -> dict[str, Any]:
+    """Turn a wire-form spec back into ``api.search`` keyword arguments."""
+    out: dict[str, Any] = {}
+    rename = {"textExact": "text_exact", "inView": "in_view",
+              "leftOf": "left_of", "rightOf": "right_of",
+              "inRow": "in_row", "inSection": "in_section",
+              "includeInert": "include_inert"}
+    for k, v in spec.items():
+        out[rename.get(k, k)] = v
+    return out
+
+
+#: `$name` as it appears in a Step's target or kwargs. Bounded by the same
+#: character class `_sub` replaces on, so what is detected and what is
+#: substituted cannot disagree.
+_PARAM_RE = re.compile(r"\$([A-Za-z_][A-Za-z0-9_]*)")
+
+
+class Step:
+    """A single Layer 1 action within a transition."""
+
+    def __init__(
+        self,
+        action: str,
+        selector: str,
+        expects_transition: bool = False,
+        *,
+        when: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        # The wire names `type` and `clear_type` are not the verbs on `api`
+        # (`type_text`, `clear_and_type`); the man pages once taught the wire
+        # name, and a step so spelled failed only when finally dispatched.
+        self.action = _STEP_VERB_ALIASES.get(action, action)
+        self.selector = selector
+        self.expects_transition = expects_transition
+        #: Run this step only if the caller supplied this optional parameter.
+        #:
+        #: Skipping by `$ref` alone is not enough for a real form. Setting one
+        #: react-select takes three steps — focus, fill, Enter — and only the
+        #: middle one mentions the value. Leave the other two unconditional and
+        #: omitting the argument still opens the menu and presses Enter on it,
+        #: which commits whatever was highlighted. `when` ties the whole group
+        #: to one argument, so "not supplied" means the field is genuinely
+        #: untouched.
+        #:
+        #: Keyword-only, so it cannot be mistaken for the legacy third
+        #: positional (`expects_transition`).
+        self.when = when
+        self.kwargs = kwargs
+
+    def resolve(self, params: dict[str, Any]) -> tuple[str, str, dict[str, Any]]:
+        """Resolve $param references, returning (action, selector, kwargs)."""
+        selector = self._sub(self.selector, params)
+        kwargs = {k: self._sub(v, params) for k, v in self.kwargs.items()}
+        return self.action, selector, kwargs
+
+    def param_refs(self) -> set[str]:
+        """Every `$name` this step substitutes, in its target or its kwargs.
+
+        Used to decide whether a step is asking for a parameter the caller
+        chose not to supply, which is how an optional field is left at whatever
+        the page already had — see `Transition.optional`.
+        """
+        refs: set[str] = set()
+        for value in (self.selector, *self.kwargs.values()):
+            if not isinstance(value, str):
+                continue
+            for token in _PARAM_RE.findall(value):
+                refs.add(token)
+        return refs
+
+    @staticmethod
+    def _sub(value: Any, params: dict[str, Any]) -> Any:
+        if not isinstance(value, str):
+            return value
+        # Whole-string param ref: "$param" → params["param"] (preserves type)
+        if value.startswith("$") and value[1:] in params:
+            return params[value[1:]]
+        # Inline interpolation: replace $param within larger strings
+        if "$" in value and params:
+            result = value
+            for key, val in params.items():
+                result = result.replace(f"${key}", str(val))
+            return result
+        return value
+
+
+class Transition:
+    """A named sequence of Layer 1 steps causing a page change."""
+
+    def __init__(
+        self,
+        name: str,
+        steps: list[Step],
+        *,
+        params: dict[str, str] | None = None,
+        optional: dict[str, str] | None = None,
+        description: str = "",
+    ) -> None:
+        self.name = name
+        self.description = description
+        self.params = params or {}
+        #: Parameters the caller may omit, name -> type, for a form field that
+        #: should keep whatever the page already had.
+        #:
+        #: A configure-style transition wants to set the two things you care
+        #: about and leave the other six alone. Without this every parameter is
+        #: required (`execute` rejects a missing one), so the only way to leave
+        #: a field at its default was a separate transition per combination.
+        #:
+        #: A step that substitutes an omitted optional parameter is *skipped* —
+        #: not run with an empty string, which would clear the field rather
+        #: than leave it. See `PageState.execute`.
+        self.optional = optional or {}
+        self.steps = steps
+
+
+class PageState:
+    """A page condition and its action space.
+
+    Constructed with configuration, bound to a DOM snapshot + API at match time.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        url_pattern: str = ".*",
+        entry: str | None = None,
+        keywords: list[str] | None = None,
+        observations: list[Observation] | None = None,
+        transitions: list[Transition] | None = None,
+        expected_timeout: float | None = None,
+    ) -> None:
+        self.name = name
+        self.url_pattern = url_pattern
+        # A real URL you can navigate to, as opposed to url_pattern, which is a
+        # matcher: r"vercel\.com/[^/]+$" identifies the dashboard but cannot be
+        # visited. Without this a widget can only be *recognised* once you are
+        # already somewhere, never entered cold — which is why opening a browser
+        # at a hand-written URL had to come first.
+        #
+        # Optional, and most states should leave it unset: "CreateTokenDialog"
+        # is reached by acting, not by navigating.
+        self.entry = entry
+        self.keywords = keywords or []
+        self.observations = {o.name: o for o in (observations or [])}
+        self.transitions = {t.name: t for t in (transitions or [])}
+        self.expected_timeout = expected_timeout  # seconds; None = use defaults
+
+        self._dom: DOMSnapshot | None = None
+        self._api: ElementaryAPI | None = None
+        self._compiled_url: re.Pattern[str] = re.compile(url_pattern)
+
+    def matches_url(self, url: str) -> bool:
+        """Check if this state's url_pattern matches the given URL."""
+        return bool(self._compiled_url.search(url))
+
+    def bind(self, dom: DOMSnapshot, api: ElementaryAPI) -> PageState:
+        """Create a bound copy with DOM/API refs."""
+        bound = PageState.__new__(PageState)
+        bound.name = self.name
+        bound.url_pattern = self.url_pattern
+        bound.entry = self.entry
+        bound.keywords = self.keywords
+        bound.observations = self.observations
+        bound.transitions = self.transitions
+        bound.expected_timeout = self.expected_timeout
+        bound._dom = dom
+        bound._api = api
+        bound._compiled_url = self._compiled_url
+        return bound
+
+    def describe(self) -> dict[str, Any]:
+        """Serializable summary for Claude."""
+        desc: dict[str, Any] = {
+            "name": self.name,
+            "url_pattern": self.url_pattern,
+            "entry": self.entry,
+            "keywords": self.keywords,
+            "observations": [
+                {"name": o.name, "description": o.description}
+                for o in self.observations.values()
+            ],
+            "transitions": [
+                {
+                    "name": t.name,
+                    "description": t.description,
+                    "params": t.params,
+                    # Advertised separately from `params`, and only when there
+                    # are any. `describe()` is how an agent learns what a
+                    # transition accepts, so an optional parameter it cannot
+                    # see is one it will never pass — and the field silently
+                    # keeps the page's default while the caller believes it
+                    # asked for something.
+                    **({"optional": t.optional} if t.optional else {}),
+                }
+                for t in self.transitions.values()
+            ],
+        }
+        if self.expected_timeout is not None:
+            desc["expected_timeout"] = self.expected_timeout
+        return desc
+
+    async def observe(self, name: str) -> Any:
+        """Execute an observation (live DOM query via bridge)."""
+        if self._api is None:
+            raise RuntimeError("PageState not bound — call bind() first")
+        obs = self.observations.get(name)
+        if obs is None:
+            available = list(self.observations.keys())
+            raise KeyError(f"No observation '{name}'. Available: {available}")
+        return await obs.run(self._api)
+
+    async def execute(self, name: str, /, **params: Any) -> PageState:
+        """Run transition steps, resolve new state.
+
+        `name` is positional-only, and that slash is load-bearing. Without it a
+        transition could never have a parameter called `name` — the most
+        obvious word for the field on any create form — because
+        ``execute("name_it", name="x")`` bound both to the same argument and
+        raised "got multiple values for argument 'name'". Nothing caught it at
+        authoring time: the Transition constructed, the widget loaded,
+        `describe()` listed the parameter, and it failed only when finally run,
+        as an arity error naming neither the widget nor the transition.
+        """
+        if self._api is None:
+            raise RuntimeError("PageState not bound — call bind() first")
+
+        transition = self.transitions.get(name)
+        if transition is None:
+            available = list(self.transitions.keys())
+            raise KeyError(f"No transition '{name}'. Available: {available}")
+
+        # Validate params
+        for pname in transition.params:
+            if pname not in params:
+                raise ValueError(f"Missing required parameter: {pname}")
+
+        unknown = set(params) - set(transition.params) - set(transition.optional)
+        if unknown:
+            # Caught here rather than ignored, because a typo in an optional
+            # name is otherwise indistinguishable from deliberately leaving the
+            # field alone — the step is skipped and the transition reports
+            # success having not done the thing you asked for.
+            raise ValueError(
+                f"Unknown parameter(s) for '{name}': {sorted(unknown)}. "
+                f"Accepts {sorted(transition.params)} "
+                f"and optionally {sorted(transition.optional)}."
+            )
+
+        # Execute steps.
+        #
+        # Every L1 verb now returns an ActionRecord dict rather than sometimes a
+        # snapshot and sometimes None, so there is no longer a value to inspect
+        # here to decide whether the page moved. A step that fails raises, which
+        # is the point: a transition that half-ran must not report the state it
+        # was aiming for.
+        for step in transition.steps:
+            # A step that needs an omitted optional parameter is skipped, which
+            # is what "defaults to whatever the form had" means. Substituting
+            # an empty string instead would *clear* the field — the opposite of
+            # leaving it alone, and silently so.
+            if step.when is not None and step.when not in params:
+                continue
+            missing = {r for r in step.param_refs() if r not in params}
+            if missing and missing <= set(transition.optional):
+                continue
+
+            action, selector, kwargs = step.resolve(params)
+            method = getattr(self._api, action, None)
+            if method is None:
+                raise AttributeError(f"ElementaryAPI has no method '{action}'")
+
+            # `expects_transition` was removed from Layer 0 -- readiness is now
+            # intrinsic to each action, so the flag has nothing to select. It is
+            # dropped rather than forwarded so an old widget still runs.
+            kwargs.pop("expects_transition", None)
+
+            # `index=` meant "the nth thing matching this". There is no nth in a
+            # ranked search, so it costs a lookup: find the candidates, take the
+            # one asked for, act on its uid. Slower than a path by one round
+            # trip -- which is the price of the old spelling, and the reason a
+            # rewritten widget should name the row instead.
+            index = kwargs.pop("index", None)
+            target = legacy_target(action, selector, kwargs)
+
+            if index and isinstance(target, dict):
+                matches = await self._api.search(**_search_kw(target))
+                if len(matches) <= index:
+                    raise RuntimeError(
+                        f"transition '{name}' step '{action}' wanted match #{index} of "
+                        f"{selector!r}, but only {len(matches)} matched"
+                    )
+                target = matches[index].as_target()
+            elif index:
+                raise RuntimeError(
+                    f"transition '{name}' step '{action}' used index={index} with a "
+                    f"path target ({selector!r}); scope the path instead"
+                )
+
+            record = await method(target, **kwargs)
+            if isinstance(record, dict) and record.get("ok") is False:
+                raise RuntimeError(
+                    f"transition '{name}' failed at step '{action}' on {selector!r}: "
+                    f"{record.get('outcome')}"
+                    + (f" -- {record['error']}" if record.get("error") else "")
+                )
+
+        # Where did that leave us? Settle, then re-resolve.
+        loading = LoadingState(self.name, name, timeout=self.expected_timeout)
+        return await loading.wait_until_ready(self._api)
+
+
+class LoadingState:
+    """Inert halt between transitions.
+
+    All it does is wait_until_ready(api) → PageState.
+    """
+
+    def __init__(self, previous_name: str, trigger: str, timeout: float | None = None) -> None:
+        self.previous_name = previous_name
+        self.trigger = trigger
+        self.timeout = timeout  # seconds; None = default 30s
+
+    async def wait_until_ready(self, api: ElementaryAPI) -> PageState:
+        """Wait for the page to settle, then resolve to a new PageState."""
+        timeout_ms = int(self.timeout * 1000) if self.timeout else None
+        await api.wait_stable(timeout_ms=timeout_ms)
+        from .registry import StateRegistry
+        return await StateRegistry.here(api)