repld-tool 0.3.2__tar.gz → 0.3.3__tar.gz

{repld_tool-0.3.2 → repld_tool-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: repld-tool
-Version: 0.3.2
+Version: 0.3.3
 Summary: Persistent Python runtime with MCP channel push. Dev shell and autonomous-agent substrate in one package.
 Keywords: repl,mcp,agent,browser
 Author: Fredrik Angelsen

{repld_tool-0.3.2 → repld_tool-0.3.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "repld-tool"
-version = "0.3.2"
+version = "0.3.3"
 description = "Persistent Python runtime with MCP channel push. Dev shell and autonomous-agent substrate in one package."
 readme = "README.md"
 authors = [

{repld_tool-0.3.2 → repld_tool-0.3.3}/src/repld/browser/observe.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 
 import asyncio
 import time
+from collections import Counter
 from dataclasses import dataclass, field
 from urllib.parse import urlparse
 
@@ -98,6 +99,11 @@ def _node_props(node: dict) -> str:
     return (" [" + ", ".join(props) + "]") if props else ""
 
 
+# A tree signature: (role, name, props) multiset over the same nodes the
+# renderer emits, used by the observation diff.
+TreeSig = Counter
+
+
 def _build_lines(
     nodes_by_id: dict[str, dict],
     children_map: dict[str, list[str]],
@@ -105,6 +111,7 @@ def _build_lines(
     depth: int,
     max_depth: int,
     lines: list[str],
+    sig: TreeSig,
 ) -> None:
     if depth > max_depth:
         return
@@ -115,7 +122,9 @@ def _build_lines(
     if role in SKIP_ROLES:
         # Still recurse through skipped roles
         for child_id in children_map.get(node_id, []):
-            _build_lines(nodes_by_id, children_map, child_id, depth, max_depth, lines)
+            _build_lines(
+                nodes_by_id, children_map, child_id, depth, max_depth, lines, sig
+            )
         return
 
     name = _node_name(node)
@@ -126,24 +135,31 @@ def _build_lines(
         label += f" {name!r}"
     label += props
     lines.append(label)
+    sig[(role, name, props)] += 1
 
     if role in LEAF_ROLES:
         return
 
     for child_id in children_map.get(node_id, []):
-        _build_lines(nodes_by_id, children_map, child_id, depth + 1, max_depth, lines)
+        _build_lines(
+            nodes_by_id, children_map, child_id, depth + 1, max_depth, lines, sig
+        )
 
 
-async def build_tree(tab: "Tab", max_depth: int = 6) -> list[str]:
+async def build_tree_sig(tab: "Tab", max_depth: int = 6) -> tuple[list[str], TreeSig]:
     """Compact accessibility tree from CDP Accessibility.getFullAXTree.
 
-    Returns list of indented text lines.
+    Returns (indented text lines, signature multiset). The signature counts
+    exactly the nodes the lines render — same roles, same depth cap — so a
+    diff of two signatures describes what a reader of the two trees would see
+    change.
     """
     result = await tab._exec("Accessibility.getFullAXTree", {})
 
+    sig: TreeSig = Counter()
     nodes = result.get("nodes", [])
     if not nodes:
-        return ["(empty tree)"]
+        return ["(empty tree)"], sig
 
     nodes_by_id: dict[str, dict] = {n["nodeId"]: n for n in nodes}
     children_map: dict[str, list[str]] = {}
@@ -161,9 +177,14 @@ async def build_tree(tab: "Tab", max_depth: int = 6) -> list[str]:
 
     lines: list[str] = []
     for root_id in root_ids:
-        _build_lines(nodes_by_id, children_map, root_id, 0, max_depth, lines)
+        _build_lines(nodes_by_id, children_map, root_id, 0, max_depth, lines, sig)
 
-    return lines or ["(empty tree)"]
+    return lines or ["(empty tree)"], sig
+
+
+async def build_tree(tab: "Tab", max_depth: int = 6) -> list[str]:
+    lines, _ = await build_tree_sig(tab, max_depth)
+    return lines
 
 
 async def build_aria_tree(tab: "Tab") -> list[str]:
@@ -339,25 +360,29 @@ async def compose_tree(
     tab: "Tab",
     session: "BrowserSession",
     max_depth: int = 8,
-) -> tuple[list[str], list["Tab"]]:
+) -> tuple[list[str], list["Tab"], dict[str, TreeSig]]:
     """Build accessibility tree with iframe children inlined.
 
-    Returns (lines, iframe_child_tabs).
+    Returns (lines, iframe_child_tabs, signatures keyed by target_id).
     """
 
     # Get base tree
-    lines = await build_tree(tab, max_depth=max_depth)
+    lines, sig = await build_tree_sig(tab, max_depth=max_depth)
+    sigs: dict[str, TreeSig] = {tab.target_id: sig}
     iframe_children = await _discover_iframe_children(tab, session)
 
     if not iframe_children:
-        return lines, []
+        return lines, [], sigs
 
     child_trees: dict[str, list[str]] = {}
     for child in iframe_children:
-        child_trees[child.target_id] = await build_tree(child, max_depth=max_depth - 2)
+        child_lines, child_sig = await build_tree_sig(child, max_depth=max_depth - 2)
+        child_trees[child.target_id] = child_lines
+        sigs[child.target_id] = child_sig
     return (
         _inline_iframe_lines(lines, iframe_children, child_trees),
         iframe_children,
+        sigs,
     )
 
 
@@ -428,6 +453,9 @@ class Observation:
     tree: list[str]
     network: list[NetworkEntry]
     console: list[str]
+    # None → no diff available (browser_open, or the page navigated);
+    # [] → diff computed, nothing changed.
+    changes: list[str] | None = None
 
 
 # ---------------------------------------------------------------------------
@@ -445,6 +473,11 @@ class PreObservation:
     # These were two separate fields until the cutoff moved to `events`; they
     # only ever held the same values, in both construction sites.
     snapshots: dict[str, int] = field(default_factory=dict)
+    # target_id → AX-tree signature for the observation diff. None (the
+    # browser_open path constructs PreObservation directly) suppresses the
+    # diff rather than reporting a fresh document as all-appeared.
+    tree_sigs: dict[str, TreeSig] | None = None
+    url: str = ""
 
 
 def _snapshot_max_ids(tabs: list["Tab"]) -> dict[str, int]:
@@ -475,12 +508,27 @@ def _snapshot_max_ids(tabs: list["Tab"]) -> dict[str, int]:
 
 
 async def pre_observe(tab: "Tab", session: "BrowserSession") -> PreObservation:
-    """Capture state before a mutation. Fast — no blocking."""
+    """Capture state before a mutation.
+
+    The signature capture fetches the same AX trees post_observe will — same
+    depths (compose_tree's 8, children at 6) — so the diff compares like with
+    like. Best-effort: a page the AX domain chokes on still gets its mutation
+    observed, just without the changes section.
+    """
     iframe_children = await _discover_iframe_children(tab, session)
     all_tabs = [tab] + iframe_children
+    tree_sigs: dict[str, TreeSig] | None = {}
+    try:
+        _, tree_sigs[tab.target_id] = await build_tree_sig(tab, max_depth=8)
+        for child in iframe_children:
+            _, tree_sigs[child.target_id] = await build_tree_sig(child, max_depth=6)
+    except Exception:
+        tree_sigs = None
     return PreObservation(
         iframe_children=iframe_children,
         snapshots=_snapshot_max_ids(all_tabs),
+        tree_sigs=tree_sigs,
+        url=tab.url,
     )
 
 
@@ -563,6 +611,98 @@ def console_delta(tabs: list["Tab"], pre_ids: dict[str, int]) -> list[str]:
     return lines
 
 
+# ---------------------------------------------------------------------------
+# Tree diff
+# ---------------------------------------------------------------------------
+
+_DIFF_MAX_LINES = 12
+
+
+def _diff_one(pre: TreeSig, post: TreeSig) -> tuple[Counter, Counter, list[tuple]]:
+    """(appeared, gone, changed) between two signatures.
+
+    An entry removed and added under the same (role, name) with different
+    props is a state change, not a departure plus an arrival — that pairing
+    is what turns "− button 'Save' [disabled] / + button 'Save'" into
+    "~ button 'Save' [disabled] → enabled".
+    """
+    added = post - pre
+    removed = pre - post
+    changed: list[tuple] = []
+    removed_by_rn: dict[tuple[str, str], list[tuple[str, int]]] = {}
+    for (role, name, props), cnt in removed.items():
+        removed_by_rn.setdefault((role, name), []).append((props, cnt))
+    for key in list(added):
+        role, name, new_props = key
+        buckets = removed_by_rn.get((role, name))
+        if not buckets:
+            continue
+        old_props, old_cnt = buckets[0]
+        n = min(added[key], old_cnt)
+        changed.append((role, name, old_props, new_props, n))
+        added[key] -= n
+        removed[(role, name, old_props)] -= n
+        if old_cnt - n:
+            buckets[0] = (old_props, old_cnt - n)
+        else:
+            buckets.pop(0)
+            if not buckets:
+                del removed_by_rn[(role, name)]
+    return +added, +removed, changed
+
+
+def _entry_str(role: str, name: str, props: str) -> str:
+    label = role
+    if name:
+        label += f" {name!r}"
+    return label + props
+
+
+def tree_diff_lines(
+    pre_sigs: dict[str, TreeSig],
+    post_sigs: dict[str, TreeSig],
+    main_target: str,
+) -> list[str]:
+    """Render the appeared/gone/changed summary, main tab first.
+
+    An iframe present on only one side reads as its whole tree
+    appearing/disappearing, which is accurate: the frame itself came or went.
+    """
+    detail: list[str] = []
+    totals = [0, 0, 0]
+    targets = [main_target] + [t for t in post_sigs if t != main_target]
+    targets += [t for t in pre_sigs if t not in post_sigs]
+    for target in targets:
+        added, removed, changed = _diff_one(
+            pre_sigs.get(target) or Counter(), post_sigs.get(target) or Counter()
+        )
+        totals[0] += sum(added.values())
+        totals[1] += sum(removed.values())
+        totals[2] += sum(n for *_, n in changed)
+        prefix = "" if target == main_target else f"{target}  "
+        for (role, name, props), cnt in sorted(added.items(), key=lambda kv: -kv[1]):
+            mult = f" ×{cnt}" if cnt > 1 else ""
+            detail.append(f"+ {prefix}{_entry_str(role, name, props)}{mult}")
+        for role, name, old, new, n in changed:
+            mult = f" ×{n}" if n > 1 else ""
+            old_s = old.strip() or "[none]"
+            new_s = new.strip() or "[none]"
+            detail.append(
+                f"~ {prefix}{_entry_str(role, name, '')} {old_s} → {new_s}{mult}"
+            )
+        for (role, name, props), cnt in sorted(removed.items(), key=lambda kv: -kv[1]):
+            mult = f" ×{cnt}" if cnt > 1 else ""
+            detail.append(f"- {prefix}{_entry_str(role, name, props)}{mult}")
+
+    if not detail:
+        return []
+    header = f"changes: {totals[0]} appeared, {totals[1]} gone, {totals[2]} changed"
+    if len(detail) > _DIFF_MAX_LINES:
+        hidden = len(detail) - _DIFF_MAX_LINES
+        detail = detail[:_DIFF_MAX_LINES] + [f"… +{hidden} more (full tree below)"]
+    return [header] + ["  " + d for d in detail]
+
+
 # ---------------------------------------------------------------------------
 # Formatting
 # ---------------------------------------------------------------------------
@@ -576,6 +716,14 @@ def format_observation(obs: Observation) -> str:
     parts.append(f"url: {obs.url} (settled in {obs.settle_ms}ms)")
     parts.append("")
 
+    # Changes — what this mutation did to the AX tree, before the full tree.
+    if obs.changes is not None:
+        if obs.changes:
+            parts.extend(obs.changes)
+        else:
+            parts.append("changes: none (AX tree unchanged)")
+        parts.append("")
+
     # Tree
     tree_count = len(obs.tree)
     parts.append(f"tree ({tree_count} nodes):")
@@ -640,7 +788,17 @@ async def post_observe(
 
     # Build composed tree — re-discovers iframes, which may differ from
     # pre.iframe_children if the mutation added/removed one.
-    tree_lines, fresh_iframes = await compose_tree(tab, session)
+    tree_lines, fresh_iframes, post_sigs = await compose_tree(tab, session)
+
+    # Diff needs a pre signature *and* the same document — after a navigation
+    # the whole tree is new, and reporting it as a few hundred appearances
+    # would bury the one section that exists to be short.
+    changes: list[str] | None = None
+    if pre.tree_sigs is not None:
+        if tab.url == pre.url:
+            changes = tree_diff_lines(pre.tree_sigs, post_sigs, tab.target_id)
+        else:
+            changes = ["changes: (page navigated — tree replaced)"]
 
     # A mutation can spawn a brand-new iframe (e.g. an OAuth popup frame)
     # that wasn't in pre.iframe_children and so never got a quiet-period
@@ -675,6 +833,7 @@ async def post_observe(
         tree=tree_lines,
         network=net_entries,
         console=console_lines,
+        changes=changes,
     )
 
     text = format_observation(obs)

{repld_tool-0.3.2 → repld_tool-0.3.3}/src/repld/browser/tab.py

@@ -10,6 +10,7 @@ import asyncio
 import base64
 import json
 import pathlib
+import re
 from dataclasses import dataclass
 from typing import Any
 
@@ -39,13 +40,38 @@ _HEARTBEAT_INTERVAL_S = 5
 _HEARTBEAT_MAX_MISSES = 3
 _HEARTBEAT_STALE_MS = _HEARTBEAT_INTERVAL_S * _HEARTBEAT_MAX_MISSES * 1000
 
-# Tab.key()'s named-key handling. Every other supported name (Enter, Escape,
-# Tab, ArrowDown, ...) already equals its own KeyboardEvent.code and needs no
-# `text` — Space is the one name whose real .key (" ") and .code ("Space")
-# diverge from each other and from the friendly name callers actually type.
+# Tab.key()'s named-key handling. Space is the one name whose real .key (" ")
+# and .code ("Space") diverge from each other and from the friendly name
+# callers actually type.
 _KEY_ALIASES = {"Space": " "}
 _KEY_CODE = {" ": "Space"}
+# Enter/Space must carry the produced character or Chromium's native
+# button/form activation never fires — the DOM keydown/keyup still dispatch.
 _KEY_TEXT = {"Enter": "\r", " ": " "}
+# Chromium's *editing* actions dispatch on windowsVirtualKeyCode, not the
+# key/code strings: without it, Backspace fires keydown/keyup but deletes
+# nothing and arrows never move the caret. Subset of Playwright's
+# USKeyboardLayout; letters/digits are computed from the character.
+_KEY_VK = {
+    "Backspace": 8,
+    "Tab": 9,
+    "Enter": 13,
+    "Escape": 27,
+    " ": 32,
+    "PageUp": 33,
+    "PageDown": 34,
+    "End": 35,
+    "Home": 36,
+    "ArrowLeft": 37,
+    "ArrowUp": 38,
+    "ArrowRight": 39,
+    "ArrowDown": 40,
+    "Insert": 45,
+    "Delete": 46,
+    **{f"F{i}": 111 + i for i in range(1, 13)},
+}
+# CDP Input.dispatchKeyEvent modifiers bitmask.
+_MODIFIER_BITS = {"Alt": 1, "Control": 2, "Ctrl": 2, "Meta": 4, "Cmd": 4, "Shift": 8}
 
 # Grace period at the end of `_reattach`, after the ready signal is satisfied.
 # The re-attach re-enables this session's CDP domains through
@@ -796,6 +822,168 @@ class Tab(TabQueryMixin):
             el, selector=selector, button=button, click_count=click_count
         )
 
+    async def hover(self, selector: str) -> Receipt:
+        """Move the mouse over an element and leave it there.
+
+        Strictly resolved like click(). The pointer stays parked on the
+        element after the call, so :hover styling and mouseenter-revealed UI
+        (menus, toolbars, tooltips) remain up for a following click — and the
+        observation's `changes:` section reports what the hover revealed.
+        """
+        await self._ensure_front()
+        el = await inject.resolve_element(self, selector)
+        await inject.check_actionable(
+            self, el, ("visible", "stable"), selector=selector
+        )
+        x, y = await self._element_center_of(el, selector)
+        receipt = await self._receipt_for(el, x, y, verb="hovering")
+        await self._exec(
+            "Input.dispatchMouseEvent", {"type": "mouseMoved", "x": x, "y": y}
+        )
+        return receipt
+
+    @staticmethod
+    def _parse_point(spec: Any) -> tuple[float, float] | None:
+        """(x, y) from an 'x,y' string or a 2-tuple; None means selector."""
+        if isinstance(spec, (tuple, list)) and len(spec) == 2:
+            return float(spec[0]), float(spec[1])
+        if isinstance(spec, str):
+            m = re.fullmatch(r"\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*", spec)
+            if m:
+                return float(m.group(1)), float(m.group(2))
+        return None
+
+    async def _resolve_drag_point(
+        self, spec: Any, *, timeout: float | None = None
+    ) -> tuple[float, float, "inject.ResolvedElement | None", str]:
+        """(x, y, element-or-None, description) for a drag endpoint."""
+        pt = self._parse_point(spec)
+        if pt is not None:
+            return pt[0], pt[1], None, f"({pt[0]:.0f},{pt[1]:.0f})"
+        kw = {} if timeout is None else {"timeout": timeout}
+        el = await inject.resolve_element(self, spec, **kw)
+        await inject.check_actionable(
+            self, el, ("visible", "stable"), selector=spec, **kw
+        )
+        x, y = await self._element_center_of(el, spec)
+        preview, sel = await inject.describe_element(self, el)
+        desc = " — ".join(p for p in (preview, sel) if p)
+        return x, y, el, desc or str(spec)
+
+    async def drag(
+        self,
+        source: "str | tuple[float, float]",
+        to: "str | tuple[float, float]",
+        *,
+        steps: int = 12,
+        duration_ms: int = 400,
+    ) -> Receipt:
+        """Mouse drag from *source* to *to* — press, paced moves, release,
+        atomically in one call. Endpoints are selectors or (x, y) / 'x,y'.
+
+        Gesture state (an app's mousemove tracking) cannot survive being
+        split across separate calls, so the whole sequence is one method.
+        Dispatches real mouse events (buttons=1 held through the moves) —
+        covers pointer/mouse-event drag (SVG editors, drag libraries, sliders);
+        native HTML5 draggable=true DnD rides a separate browser pipeline
+        these events don't start, so a `changes: none` observation after
+        dragging one is the tell.
+
+        A drop target that only appears once the drag starts (drop zones) is
+        handled: if *to* doesn't resolve up front, the drag begins and the
+        selector is re-resolved mid-gesture.
+        """
+        await self._ensure_front()
+        x1, y1, src_el, src_desc = await self._resolve_drag_point(source)
+        if src_el is not None:
+            data = await inject.hit_receipt(self, src_el, x1, y1)
+            if data.get("hit") is not None and not data.get("related", True):
+                h = data["hit"]
+                hdesc = " — ".join(p for p in (h.get("preview"), h.get("sel")) if p)
+                push_kind(
+                    f"drag source point ({x1:.0f},{y1:.0f}) occluded by {hdesc}",
+                    "browser_warning",
+                    target=self.target_id,
+                )
+
+        # Resolve the drop point before pressing when it already exists —
+        # a wrong-direction first nudge matters at 6 px drag scale.
+        deferred_target = False
+        try:
+            x2, y2, tgt_el, tgt_desc = await self._resolve_drag_point(to, timeout=0.5)
+        except RuntimeError:
+            deferred_target = True
+            x2 = y2 = 0.0
+            tgt_el, tgt_desc = None, str(to)
+
+        await self._exec(
+            "Input.dispatchMouseEvent", {"type": "mouseMoved", "x": x1, "y": y1}
+        )
+        await self._exec(
+            "Input.dispatchMouseEvent",
+            {
+                "type": "mousePressed",
+                "x": x1,
+                "y": y1,
+                "button": "left",
+                "buttons": 1,
+                "clickCount": 1,
+            },
+        )
+        # From here the button is down — never leave the page mid-drag: the
+        # release in `finally` fires at the last point the pointer reached.
+        cur_x, cur_y = x1, y1
+        try:
+            if deferred_target:
+                # Cross the typical dragstart threshold so drag-revealed drop
+                # zones mount, then resolve the selector for real.
+                cur_x, cur_y = x1 + 4, y1 + 4
+                await self._exec(
+                    "Input.dispatchMouseEvent",
+                    {"type": "mouseMoved", "x": cur_x, "y": cur_y, "buttons": 1},
+                )
+                x2, y2, tgt_el, tgt_desc = await self._resolve_drag_point(to)
+
+            delay = duration_ms / max(steps, 1) / 1000
+            for i in range(1, steps + 1):
+                frac = i / steps
+                cur_x = x1 + (x2 - x1) * frac
+                cur_y = y1 + (y2 - y1) * frac
+                await self._exec(
+                    "Input.dispatchMouseEvent",
+                    {"type": "mouseMoved", "x": cur_x, "y": cur_y, "buttons": 1},
+                )
+                await asyncio.sleep(delay)
+
+            drop_note = ""
+            warning = False
+            if tgt_el is not None:
+                data = await inject.hit_receipt(self, tgt_el, x2, y2)
+                if data.get("hit") is not None and not data.get("related", True):
+                    h = data["hit"]
+                    hdesc = " — ".join(p for p in (h.get("preview"), h.get("sel")) if p)
+                    drop_note = f" — warning: drop point hits {hdesc}"
+                    warning = True
+        finally:
+            await self._exec(
+                "Input.dispatchMouseEvent",
+                {
+                    "type": "mouseReleased",
+                    "x": cur_x,
+                    "y": cur_y,
+                    "button": "left",
+                    "buttons": 0,
+                    "clickCount": 1,
+                },
+            )
+        return Receipt(
+            line=(
+                f"dragged: {src_desc} ({x1:.0f},{y1:.0f}) → "
+                f"({x2:.0f},{y2:.0f}) {tgt_desc}{drop_note}"
+            ),
+            warning=warning,
+        )
+
     async def type_text(
         self,
         selector: str,
@@ -827,17 +1015,7 @@ class Tab(TabQueryMixin):
         )
 
         before = await inject.read_value(self, el)
-        for char in text:
-            for event_type in ("keyDown", "keyUp"):
-                await self._exec(
-                    "Input.dispatchKeyEvent",
-                    {
-                        "type": event_type,
-                        "text": char if event_type == "keyDown" else "",
-                    },
-                )
-            if delay_ms > 0:
-                await asyncio.sleep(delay_ms / 1000)
+        await self._type_chars(text, delay_ms=delay_ms)
 
         after = await inject.read_value(self, el)
         if after == text:
@@ -865,14 +1043,32 @@ class Tab(TabQueryMixin):
             await self.key("Enter")
         return receipt
 
+    async def _type_chars(self, text: str, *, delay_ms: int = 0) -> None:
+        """Key events into whatever holds focus — the shared core of
+        type_text and select_option's type-to-filter."""
+        for char in text:
+            for event_type in ("keyDown", "keyUp"):
+                await self._exec(
+                    "Input.dispatchKeyEvent",
+                    {
+                        "type": event_type,
+                        "text": char if event_type == "keyDown" else "",
+                    },
+                )
+            if delay_ms > 0:
+                await asyncio.sleep(delay_ms / 1000)
+
     async def select_option(self, selector: str, option: str) -> Receipt:
         """Select *option* in a dropdown — native <select> or custom listbox.
 
         Native <select>: finds the option by label (else value) and sets it
         through the prototype setter + input/change events. Custom widgets
         (react-select-style): clicks the field, waits for a role=option
-        matching *option* (exact, then substring), clicks it. A miss lists
-        the visible options' accessible names.
+        matching *option* (exact, then substring), clicks it. When the click
+        focuses an element declaring aria-autocomplete, *option* is typed
+        into it first and resolution runs against the filtered listbox —
+        which is what reaches an option a virtualized list hasn't rendered.
+        A miss lists the visible options' accessible names.
         """
         await self._ensure_front()
         el = await inject.resolve_element(self, selector)
@@ -895,6 +1091,25 @@ class Tab(TabQueryMixin):
             return Receipt(line=f'selected "{option}" in {tdesc}')
 
         await self._click_element(el, selector=selector)
+
+        # Type-to-filter. aria-autocomplete on the freshly-focused element is
+        # the widget's own declaration that typing narrows the listbox; going
+        # through the filter is the only route to an option a virtualized
+        # list keeps below its render window, where waiting can never make it
+        # appear. The keystrokes go to document.activeElement regardless, so
+        # the focused element is also the right one to ask.
+        filtered = False
+        ac = await inject.call_engine(
+            self,
+            "function() { const a = this.document.activeElement;"
+            " const ac = a && a.getAttribute && a.getAttribute('aria-autocomplete');"
+            " return !!ac && ac !== 'none'; }",
+            [],
+        )
+        if ac.get("result", {}).get("value"):
+            await self._type_chars(option)
+            filtered = True
+
         opt_label = f"option {option!r}"
         opt_selectors = [
             f"role=option[name={selector_mod._text_body(option, exact=True)}]",
@@ -908,13 +1123,14 @@ class Tab(TabQueryMixin):
             raise
         except RuntimeError as exc:
             names = await inject.list_option_names(self)
+            via = " and typing it into the filter" if filtered else ""
             if names:
                 raise RuntimeError(
-                    f"{opt_label} not found after opening {tdesc}"
+                    f"{opt_label} not found after opening {tdesc}{via}"
                     f" — visible options: {names}"
                 ) from exc
             raise RuntimeError(
-                f"{opt_label} not found — no listbox opened after clicking {tdesc}"
+                f"{opt_label} not found — no listbox opened after clicking {tdesc}{via}"
             ) from exc
         await inject.check_actionable(
             self, opt_el, ("visible", "stable"), selector=opt_label
@@ -961,26 +1177,80 @@ class Tab(TabQueryMixin):
             verified = bool(v.get("result", {}).get("value"))
         except Exception:
             pass
-        suffix = "" if verified else " (selection not verified)"
+        suffix = " (typed to filter)" if filtered else ""
+        suffix += "" if verified else " (selection not verified)"
         return Receipt(line=f'selected "{option}" in {tdesc}{suffix}')
 
     async def key(self, key: str) -> None:
-        """Dispatch a keyDown+keyUp pair for a named key (e.g. "Enter", "Escape", "Space").
+        """Dispatch one key press — a named key, a printable character, or a
+        modifier combo.
+
+        Accepts KeyboardEvent.key names ("Enter", "Backspace", "ArrowLeft",
+        "F5", "Space" as an alias for " "), single printable characters ("a"),
+        and "+"-joined combos with Ctrl/Control, Alt, Shift, Cmd/Meta
+        modifiers ("Ctrl+A", "Shift+Tab"). A trailing "+" is the plus key
+        itself ("Ctrl++").
+        """
+        await self._ensure_front()
+        await self._dispatch_key(key)
 
-        `key` is a KeyboardEvent.key value ("Space" is accepted as a friendly
-        alias for its real value, " ").
+    async def keys(self, keys: list[str], *, delay_ms: int = 0) -> None:
+        """Dispatch a sequence of key()/combo presses in one call.
+
+        One round trip for a keyboard navigation flow ("Ctrl+A", then
+        "Backspace", then arrows) instead of one per keypress. delay_ms adds a
+        pause between presses for apps that debounce key handling.
         """
         await self._ensure_front()
+        for k in keys:
+            await self._dispatch_key(k)
+            if delay_ms:
+                await asyncio.sleep(delay_ms / 1000)
+
+    async def _dispatch_key(self, spec: str) -> None:
+        if spec.endswith("+"):
+            # "Ctrl++" / bare "+": the key is a literal plus.
+            key = "+"
+            mod_part = spec[:-1].rstrip("+")
+            mods = mod_part.split("+") if mod_part else []
+        else:
+            *mods, key = spec.split("+")
+        modifiers = 0
+        for m in mods:
+            bit = _MODIFIER_BITS.get(m)
+            if bit is None:
+                raise ValueError(
+                    f"unknown modifier {m!r} in {spec!r} — use Ctrl/Alt/Shift/Cmd"
+                )
+            modifiers |= bit
+
         key = _KEY_ALIASES.get(key, key)
         code = _KEY_CODE.get(key, key)
+        vk = _KEY_VK.get(key)
+        if len(key) == 1:
+            ch = key.upper()
+            if ch.isalpha():
+                code = f"Key{ch}"
+            elif ch.isdigit():
+                code = f"Digit{ch}"
+            if vk is None and (ch.isalpha() or ch.isdigit()):
+                vk = ord(ch)
         text = _KEY_TEXT.get(key)
+        # A printable key produces its character — unless Ctrl/Alt/Meta is
+        # held, where the browser runs the shortcut instead of inserting text.
+        if text is None and len(key) == 1 and not (modifiers & 0b111):
+            text = key
+
         for event_type in ("keyDown", "keyUp"):
-            params: dict[str, str] = {"type": event_type, "key": key, "code": code}
-            # Chromium's native button/checkbox/form activation for Enter and
-            # Space only fires when the keyDown event also carries the
-            # produced character in `text` — verified live: without it, the
-            # DOM keydown/keyup still dispatch but no click ever follows,
-            # indistinguishable from the key doing nothing.
+            params: dict[str, Any] = {
+                "type": event_type,
+                "key": key,
+                "code": code,
+                "modifiers": modifiers,
+            }
+            if vk is not None:
+                params["windowsVirtualKeyCode"] = vk
+                params["nativeVirtualKeyCode"] = vk
             if event_type == "keyDown" and text:
                 params["text"] = text
             await self._exec("Input.dispatchKeyEvent", params)

{repld_tool-0.3.2 → repld_tool-0.3.3}/src/repld/browser_dispatch.py

@@ -346,7 +346,7 @@ class BrowserDispatchMixin:
         tab = self._get_tab(browser, args)
         session = self._session_for(browser, tab)
         if args.get("mode") == "ax":
-            lines, _ = self._run_async(compose_tree(tab, session))
+            lines, _, _ = self._run_async(compose_tree(tab, session))
         else:
             lines, _ = self._run_async(compose_aria_tree(tab, session))
         return "\n".join(lines)
@@ -410,11 +410,14 @@ class BrowserDispatchMixin:
 
     def _bh_key(self, browser, args):
         tab = self._get_tab(browser, args)
+        if args.get("keys"):
+            mutate = lambda: self._run_async(tab.keys(list(args["keys"])))  # noqa: E731
+        elif args.get("key"):
+            mutate = lambda: self._run_async(tab.key(args["key"]))  # noqa: E731
+        else:
+            raise ValueError("browser_key needs 'key' or 'keys'")
         return self._observed_mutation(
-            browser,
-            tab,
-            lambda: self._run_async(tab.key(args["key"])),
-            timeout=_SETTLE_INTERACTION_S,
+            browser, tab, mutate, timeout=_SETTLE_INTERACTION_S
         )
 
     def _bh_click(self, browser, args):
@@ -448,6 +451,37 @@ class BrowserDispatchMixin:
         )
         return f"{captured['receipt']}\n\n{obs}"
 
+    def _bh_hover(self, browser, args):
+        tab = self._get_tab(browser, args)
+        captured: dict = {}
+
+        def mutate():
+            captured["receipt"] = self._run_async(tab.hover(args["selector"]))
+
+        obs = self._observed_mutation(
+            browser, tab, mutate, timeout=_SETTLE_INTERACTION_S
+        )
+        return f"{captured['receipt']}\n\n{obs}"
+
+    def _bh_drag(self, browser, args):
+        tab = self._get_tab(browser, args)
+        captured: dict = {}
+
+        def mutate():
+            captured["receipt"] = self._run_async(
+                tab.drag(
+                    args["from"],
+                    args["to"],
+                    steps=int(args.get("steps", 12)),
+                    duration_ms=int(args.get("duration_ms", 400)),
+                )
+            )
+
+        obs = self._observed_mutation(
+            browser, tab, mutate, timeout=_SETTLE_INTERACTION_S
+        )
+        return f"{captured['receipt']}\n\n{obs}"
+
     def _bh_select(self, browser, args):
         tab = self._get_tab(browser, args)
         captured: dict = {}
@@ -483,6 +517,8 @@ class BrowserDispatchMixin:
         "browser_click": _bh_click,
         "browser_type": _bh_type,
         "browser_select": _bh_select,
+        "browser_hover": _bh_hover,
+        "browser_drag": _bh_drag,
         "browser_controls": _bh_controls,
         "browser_invoke": _bh_invoke,
     }

{repld_tool-0.3.2 → repld_tool-0.3.3}/src/repld/help.py

@@ -64,12 +64,17 @@ _BROWSER_MODEL = (
     "waits for visible/enabled/stable; click/type return a receipt line naming "
     "what was actually hit. type verifies the value landed, falling back to the "
     "native setter for framework-controlled inputs. browser_select drives "
-    "dropdowns (native <select> or custom listbox). "
+    "dropdowns (native <select> or custom listbox; an aria-autocomplete field "
+    "gets the option typed in as a filter, reaching virtualized lists). "
+    "browser_hover parks the pointer on an element (hover-revealed UI stays "
+    "up); browser_drag runs press→moves→release atomically in one call "
+    "(selectors or 'x,y' endpoints). "
     "browser_tree default is an aria snapshot with [ref=eN] handles — reuse as "
     "aria-ref=eN selectors until the next snapshot or navigation; mode='ax' is "
     "the raw CDP tree. "
-    "Mutations (click/type/select/navigate/key/open) settle then return "
-    "receipt + tree + network delta + console delta. "
+    "Mutations (click/type/select/hover/drag/navigate/key/open) settle then "
+    "return receipt + a changes: AX-diff (what appeared/disappeared/changed "
+    "state) + tree + network delta + console delta. "
     "Tree crosses iframes. Network separates API calls from assets. "
     "get()/open() capture request/response bodies; watch() attaches lightweight. "
     "Read workflow: network → request → body. "
@@ -504,13 +509,42 @@ Convention: add data-testid to your root layout component.
       label (else value), sets it via the prototype setter + input/change
       events.  Custom widgets (react-select-style): clicks the field, waits
       for a role=option matching the name (exact, then substring), clicks
-      it.  A miss lists the visible options' accessible names.
+      it.  When the click focuses an element declaring aria-autocomplete,
+      the option text is typed in first and resolution runs against the
+      filtered listbox — reaches options a virtualized list hasn't rendered.
+      A miss lists the visible options' accessible names.
+
+  tab.hover(selector)                                        → Receipt
+      Move the mouse over an element and leave it parked there — :hover
+      styling and mouseenter-revealed UI (menus, toolbars, tooltips) stay up
+      for a following click, and the observation's changes: section reports
+      what the hover revealed.  Strict resolution + visible/stable wait like
+      click.
+
+  tab.drag(source, to, *, steps=12, duration_ms=400)         → Receipt
+      Mouse drag in one call: press on source, paced mouseMoved events with
+      the button held, release on to.  Endpoints are selectors (strictly
+      resolved, scrolled into view) or (x, y) tuples / 'x,y' strings.  A
+      drop target that only appears once the drag starts is re-resolved
+      mid-gesture.  Covers pointer/mouse-event drag (SVG editors, sliders,
+      drag libraries); native HTML5 draggable=true DnD rides a different
+      browser pipeline these events don't start — an observation saying
+      "changes: none" after dragging one is the tell.  The Receipt names
+      both endpoints and warns if the drop point was occluded.
 
   tab.key(key)                                               → None
-      Dispatch a keyDown+keyUp pair for a named key (e.g. "Enter", "Escape",
-      "Space"). Enter and Space carry the produced character so Chromium's
-      native button/form activation fires, not just the DOM keydown/keyup —
-      without it a focused button silently doesn't click.
+      Dispatch one key press: named keys ("Enter", "Backspace", "ArrowLeft",
+      "F5", "Space"), printable characters ("a"), and Ctrl/Alt/Shift/Cmd
+      combos ("Ctrl+A", "Shift+Tab"; trailing "+" is the plus key).  Carries
+      the virtual key code, so editing actions actually happen — Backspace
+      deletes, arrows move the caret — and Enter/Space carry their character
+      so native button/form activation fires.
+
+  tab.keys(keys, *, delay_ms=0)                              → None
+      A sequence of key()/combo presses in one call — one round trip for a
+      keyboard flow ("Ctrl+A", "Backspace", "ArrowDown", "Enter") instead of
+      one per keypress.  delay_ms pauses between presses for apps that
+      debounce key handling.
 
   tab.tap(selector_or_x, y=None)                             → Receipt
       Touch tap via Input.dispatchTouchEvent (touchstart/touchend).
@@ -790,7 +824,7 @@ Suppress filter (opt-in):
 
 == Selectors ==
 
-Same syntax across click, tap, type_text, select_option, wait_for:
+Same syntax across click, tap, type_text, select_option, hover, drag, wait_for:
 
   .css-class, #id, [attr], tag                        CSS
   [data-testid='name']                                CSS (recommended for own code)
@@ -899,10 +933,12 @@ wait_for_idle() and the MCP observation pipeline use the same settle logic:
 
 MCP browser tools (browser_click, browser_type, browser_navigate, etc.) run
   the full observation pipeline: pre_observe → mutate → settle → post_observe.
-  They automatically wait for network idle and return tree + network delta +
-  console delta.  This means each MCP call returns only after the page is
-  stable — the next call's auto-wait (2s) rarely fires because the element
-  is already in the DOM.
+  They automatically wait for network idle and return a changes: section (an
+  AX-tree diff of what the mutation made appear/disappear/change state —
+  "changes: none" means the page visibly ignored the action) + tree +
+  network delta + console delta.  This means each MCP call returns only
+  after the page is stable — the next call's auto-wait (2s) rarely fires
+  because the element is already in the DOM.
 
 exec-based mutations (calling tab.click(), tab.type_text() etc. in Python code)
   do NOT auto-settle.  The method returns as soon as the CDP command completes.
@@ -1232,8 +1268,11 @@ Tab (async unless noted):
   tab.swipe(x1, y1, x2, y2, steps=, duration_ms=)  → None (touch scroll)
   tab.scroll(selector, dy=, dx=, steps=, duration_ms=) → None (touch-scroll container)
   tab.type_text(selector, text, delay_ms=, press_enter=)  → Receipt (clears first; verifies value, native-setter fallback for controlled inputs)
-  tab.select_option(selector, option)              → Receipt (native <select> or custom listbox; a miss lists the options)
-  tab.key(key)                                     → None (keyDown+keyUp, e.g. "Enter"/"Space" trigger native button activation)
+  tab.select_option(selector, option)              → Receipt (native <select> or custom listbox; types into an aria-autocomplete filter to reach virtualized options; a miss lists the options)
+  tab.hover(selector)                              → Receipt (park the pointer on an element; hover-revealed UI stays up)
+  tab.drag(source, to, steps=, duration_ms=)       → Receipt (press→paced moves→release in one call; endpoints are selectors or (x,y)/'x,y')
+  tab.key(key)                                     → None (named keys, chars, "Ctrl+A" combos; VK-coded so Backspace/arrows actually edit)
+  tab.keys(keys, delay_ms=)                        → None (sequence of presses in one call)
   tab.wait_for(selector, timeout=5)                → None (wait for element to appear)
   tab.wait_for_idle(timeout=5, quiet=0.5)          → int  (network idle; returns settle ms)
   tab.fetch(url, method=, body=, headers=)         → {status, ok, body, base64Encoded}
@@ -1300,7 +1339,7 @@ Browser:
   (HMR/navigation) it re-attaches and waits again. navigate() and reload()
   also wait for it. Convention: add data-testid to your root layout component.
 
-Selectors (click/tap/type_text/select_option):
+Selectors (click/tap/type_text/select_option/hover/drag):
   .css-class, #id, [attr], tag           CSS
   [data-testid='name']                   CSS (recommended for own code)
   text=Submit                            exact text match

{repld_tool-0.3.2 → repld_tool-0.3.3}/src/repld/protocol.py

@@ -221,8 +221,11 @@ TOOLS = [
     {
         "name": "browser_key",
         "description": (
-            "Send a key press (Enter, Escape, Tab, ArrowDown, etc). "
-            "Returns observation (tree + network + console delta after settle)."
+            "Send key presses. Named keys (Enter, Escape, Backspace, "
+            "ArrowDown), printable characters, and Ctrl/Alt/Shift/Cmd combos "
+            "('Ctrl+A', 'Shift+Tab'). Pass keys=[...] for a whole sequence in "
+            "one call. Returns observation (tree + network + console delta "
+            "after settle)."
         ),
         "inputSchema": {
             "type": "object",
@@ -230,10 +233,15 @@ TOOLS = [
                 "target": _TARGET_PARAM,
                 "key": {
                     "type": "string",
-                    "description": "Key name: Enter, Escape, Tab, ArrowDown, etc.",
+                    "description": "One key or combo: Enter, Backspace, Ctrl+A, ...",
+                },
+                "keys": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Sequence of keys/combos, pressed in order",
                 },
             },
-            "required": ["target", "key"],
+            "required": ["target"],
         },
     },
     {
@@ -353,6 +361,63 @@ TOOLS = [
             "required": ["target", "selector", "option"],
         },
     },
+    {
+        "name": "browser_hover",
+        "description": (
+            "Hover an element, strictly resolved like browser_click, and "
+            "leave the pointer parked on it — hover-revealed UI (menus, "
+            "toolbars, tooltips) stays up for a following browser_click, and "
+            "the observation's changes: section reports what the hover "
+            "revealed. Returns receipt + observation."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "target": _TARGET_PARAM,
+                "selector": _SELECTOR_PARAM,
+            },
+            "required": ["target", "selector"],
+        },
+    },
+    {
+        "name": "browser_drag",
+        "description": (
+            "Mouse drag in a single call: press, paced moves with the button "
+            "held, release — gesture state can't survive being split across "
+            "calls. Endpoints are selectors (strictly resolved) or 'x,y' "
+            "coordinates. A drop target that only appears once the drag "
+            "starts is re-resolved mid-gesture. Covers pointer/mouse-event "
+            "drag (SVG editors, sliders, drag libraries); native HTML5 "
+            "draggable DnD rides a different browser pipeline — an "
+            "observation saying 'changes: none' after dragging one is the "
+            "tell. Returns receipt + observation."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "target": _TARGET_PARAM,
+                "from": {
+                    "type": "string",
+                    "description": "Drag origin: selector or 'x,y'",
+                },
+                "to": {
+                    "type": "string",
+                    "description": "Drop point: selector or 'x,y'",
+                },
+                "steps": {
+                    "type": "integer",
+                    "default": 12,
+                    "description": "Intermediate move events",
+                },
+                "duration_ms": {
+                    "type": "integer",
+                    "default": 400,
+                    "description": "Total move time across the steps",
+                },
+            },
+            "required": ["target", "from", "to"],
+        },
+    },
     {
         "name": "browser_console",
         "description": "Query captured console messages for a tab (console.log, errors, exceptions).",
@@ -486,6 +551,8 @@ _TOOL_ANNOTATIONS = {
     "browser_click": {"openWorldHint": True},
     "browser_type": {"openWorldHint": True},
     "browser_select": {"openWorldHint": True},
+    "browser_hover": {"openWorldHint": True},
+    "browser_drag": {"openWorldHint": True},
     "browser_invoke": {"openWorldHint": True},
 }