@widgex/wgx 0.0.0-stage → 0.4.2

package/python/xactor/states/registry.py

@@ -0,0 +1,274 @@
+"""StateRegistry — maps URL patterns to PageState templates."""
+
+from __future__ import annotations
+
+from typing import Any, TYPE_CHECKING
+
+from .base import PageState, Observation, Transition, Step
+
+if TYPE_CHECKING:
+    from ..api import ElementaryAPI
+    from ..dom import DOMSnapshot
+
+
+class StateRegistry:
+    """Singleton registry mapping URL patterns → PageState templates.
+
+    Uses class-level storage so it works with both import and exec loading.
+
+    Also the source of truth for "where is the agent right now" — resolve()
+    publishes every change over the bridge so the IDE can render it live.
+    """
+
+    _states: dict[str, PageState] = {}
+    _adjacency: dict[str, list[str]] = {}
+
+    # Live position, published to the IDE on change.
+    _current: str | None = None
+    _current_url: str | None = None
+    # Fingerprint of the last graph we published, so the (large) graph payload
+    # rides along only when the registry itself changed.
+    _published_graph: tuple[str, ...] | None = None
+
+    @classmethod
+    def add(cls, state: PageState, transitions_to: list[str] | None = None) -> None:
+        """Register a state + its adjacency list."""
+        cls._states[state.name] = state
+        if transitions_to:
+            cls._adjacency[state.name] = transitions_to
+
+    # ── Live position reporting ──────────────────────────────────────
+
+    @classmethod
+    def graph(cls) -> dict[str, Any]:
+        """Serializable machine definition: states plus the adjacency graph."""
+        return {
+            "states": [s.describe() for s in cls._states.values()],
+            "adjacency": {k: list(v) for k, v in cls._adjacency.items()},
+        }
+
+    @classmethod
+    def _fingerprint(cls) -> tuple[str, ...]:
+        return tuple(sorted(cls._states)) + ("|",) + tuple(
+            f"{k}>{','.join(v)}" for k, v in sorted(cls._adjacency.items())
+        )
+
+    @classmethod
+    def publish(cls, state_name: str | None = None, url: str | None = None,
+                *, force: bool = False) -> None:
+        """Tell the IDE where the agent is. Never raises — reporting must not
+        break automation, and the browser backend can run with no bridge.
+        """
+        previous = cls._current
+        if state_name is not None:
+            cls._current = state_name
+        if url is not None:
+            cls._current_url = url
+
+        fingerprint = cls._fingerprint()
+        graph_changed = fingerprint != cls._published_graph
+        if not force and not graph_changed and previous == cls._current:
+            return  # nothing new to say
+
+        payload: dict[str, Any] = {
+            "event": "xactor.state",
+            "state": cls._current,
+            "url": cls._current_url,
+            "previous": previous if previous != cls._current else None,
+        }
+        if graph_changed or force:
+            payload["graph"] = cls.graph()
+            cls._published_graph = fingerprint
+
+        try:
+            from .. import bridge
+
+            bridge._emit(payload)
+        except Exception:
+            pass
+
+    @classmethod
+    def current(cls) -> str | None:
+        """Last resolved state name, if any."""
+        return cls._current
+
+    @classmethod
+    async def here(cls, api: ElementaryAPI) -> PageState:
+        """The bound PageState for the page as it is right now.
+
+        Use this. `current()` returns a *name*, which you cannot call anything
+        on — getting something callable meant knowing to write
+        `await registry.resolve(await api.snapshot(), api)`, which was written
+        down nowhere. Agents that could not find it fell back to copying a
+        widget's observation JS into `api.evaluate`, which is the thing the
+        whole layer exists to make unnecessary.
+
+            state = await registry.here(api)
+            rows  = await state.observe("existing_tokens")
+            state = await state.execute("create_token")
+        """
+        return await cls.resolve(None, api)
+
+    @classmethod
+    async def enter(cls, api: ElementaryAPI, state_name: str | None = None) -> PageState:
+        """Navigate to a state's `entry` URL and resolve.
+
+        This is how a widget is entered cold. With no name, the first registered
+        state that declares an `entry` is the home.
+
+        Resolution is deliberately not asserted against `state_name`: arriving
+        somewhere other than where you aimed — a login wall, a consent screen —
+        is information the caller needs, not an error to raise. Check
+        `.name` on what you get back.
+        """
+        if state_name is None:
+            enterable = [s for s in cls._states.values() if getattr(s, "entry", None)]
+            if not enterable:
+                raise ValueError(
+                    "No loaded state declares an entry URL, so there is nowhere to "
+                    "enter. Add entry=\"https://...\" to the widget's home state."
+                )
+            target = enterable[0]
+        else:
+            target = cls._states.get(state_name)
+            if target is None:
+                raise KeyError(
+                    f"No state '{state_name}'. Loaded: {list(cls._states)}"
+                )
+            if not getattr(target, "entry", None):
+                raise ValueError(
+                    f"State '{state_name}' has no entry URL — url_pattern is a matcher, "
+                    "not a destination. Reach it with a transition, or give it entry=."
+                )
+
+        await api.navigate(target.entry)
+        snap = await api.wait_stable()
+        return await cls.resolve(snap, api)
+
+    @classmethod
+    async def resolve(cls, dom: "DOMSnapshot | None", api: ElementaryAPI) -> PageState:
+        """URL-match -> bind -> return. Falls back to UNKNOWN_STATE.
+
+        When several states match the same URL -- which is the normal case for a
+        site whose dialogs live at one address -- they are disambiguated by
+        scoring each state's keywords against the visible page text.
+
+        `dom` is accepted for the widgets that still pass one, but nothing needs
+        it any more: asking the page for its URL costs one cheap call, where a
+        snapshot used to pull the whole accessibility tree and every cookie on
+        the domain just to read `.url` off it.
+        """
+        if dom is not None and getattr(dom, "url", None):
+            url = dom.url
+        else:
+            state = await api.get_state()
+            url = (state or {}).get("url", "")
+
+        candidates = [s for s in cls._states.values() if s.matches_url(url)]
+        if not candidates:
+            cls.publish(UNKNOWN_STATE.name, url)
+            return UNKNOWN_STATE.bind(dom, api)
+        if len(candidates) == 1:
+            cls.publish(candidates[0].name, url)
+            return candidates[0].bind(dom, api)
+
+        # Several states claim this URL -- a site whose dialogs all live at one
+        # address. Score each one's keywords against what is actually rendered.
+        try:
+            page_text = await api.evaluate("document.body.innerText")
+            if not isinstance(page_text, str):
+                page_text = ""
+        except Exception:
+            page_text = ""
+        if not page_text and dom is not None:
+            page_text = dom.text_content()
+        page_text = page_text.lower()
+
+        best, best_score = candidates[0], -1
+        for state in candidates:
+            score = sum(1 for kw in state.keywords if kw.lower() in page_text)
+            if score > best_score:
+                best, best_score = state, score
+        cls.publish(best.name, url)
+        return best.bind(dom, api)
+
+    @classmethod
+    def all_states(cls) -> list[dict[str, Any]]:
+        """Return descriptions of all registered states."""
+        return [s.describe() for s in cls._states.values()]
+
+    @classmethod
+    def reachable_from(cls, state_name: str) -> list[str]:
+        """Return state names reachable from the given state."""
+        return cls._adjacency.get(state_name, [])
+
+    @classmethod
+    def clear(cls) -> None:
+        """Remove all registered states."""
+        cls._states.clear()
+        cls._adjacency.clear()
+        cls._current = None
+        cls._current_url = None
+        cls._published_graph = None
+
+
+# ── UnknownPageState (fallback) ──────────────────────────────────
+
+UNKNOWN_STATE = PageState(
+    "UnknownPage",
+    url_pattern=".*",
+    keywords=["unknown", "generic", "fallback"],
+    observations=[
+        Observation(
+            "links",
+            description="All links on the page",
+            js="Array.from(document.querySelectorAll('a[href]')).map(a => ({text: a.textContent?.trim(), href: a.href})).filter(l => l.text)",
+        ),
+        Observation(
+            "buttons",
+            description="All buttons on the page",
+            js="Array.from(document.querySelectorAll('button, [role=\"button\"], input[type=\"submit\"]')).map(b => ({text: b.textContent?.trim() || b.value || b.getAttribute('aria-label'), type: b.tagName.toLowerCase()}))",
+        ),
+        Observation(
+            "inputs",
+            description="All input fields on the page",
+            js="Array.from(document.querySelectorAll('input:not([type=\"hidden\"]), textarea, select')).map(i => ({type: i.type || i.tagName.toLowerCase(), name: i.name, id: i.id, placeholder: i.placeholder, value: i.value}))",
+        ),
+        Observation(
+            "headings",
+            description="All headings on the page",
+            js="Array.from(document.querySelectorAll('h1, h2, h3')).map(h => ({level: h.tagName, text: h.textContent?.trim()}))",
+        ),
+        Observation(
+            "title",
+            description="Page title",
+            js="document.title",
+        ),
+    ],
+    transitions=[
+        Transition(
+            "click_element",
+            description="Click any element by selector",
+            params={"selector": "str"},
+            steps=[
+                Step("click", "$selector", expects_transition=True),
+            ],
+        ),
+        Transition(
+            "type_into",
+            description="Type text into an element",
+            params={"selector": "str", "text": "str"},
+            steps=[
+                Step("clear_and_type", "$selector", text="$text"),
+            ],
+        ),
+        Transition(
+            "navigate_to",
+            description="Navigate to a URL",
+            params={"url": "str"},
+            steps=[
+                Step("navigate", "$url"),
+            ],
+        ),
+    ],
+)