Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

chore: clarify handoff limitations and e2e test

Luigi Agostiec77996f9b47
diff --git a/dashboard/src/components/molecules/TabsChart.tsx b/dashboard/src/components/molecules/TabsChart.tsx
index ef94d0e9..aa888b70 100644
--- a/dashboard/src/components/molecules/TabsChart.tsx
+++ b/dashboard/src/components/molecules/TabsChart.tsx
@@ -8,7 +8,7 @@ import {
CartesianGrid,
ResponsiveContainer,
} from "recharts";
-import type { TooltipContentProps } from "recharts";
+import type { TooltipContentProps, TooltipProps } from "recharts";
import type {
TabDataPoint,
MemoryDataPoint,
@@ -268,9 +268,9 @@ export default function TabsChart({
return vals;
}, [mergedData, instances, instanceColors]);
- const tooltipContent = ((props: TooltipContentProps<number, string>) => (
- <GlassTooltip {...props} instances={instances} />
- )) as any;
+ const tooltipContent: NonNullable<TooltipProps<number, string>["content"]> = (
+ props: TooltipContentProps<number, string>,
+ ) => <GlassTooltip {...props} instances={instances} />;
if (mergedData.length < 2) {
return (
diff --git a/docs/commands.md b/docs/commands.md
index 8c1c5bfd..3201e51b 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -73,6 +73,10 @@ pinchtab type <selector> <text> # Type via key events
pinchtab fill <selector> <text> # Fill directly
pinchtab press <key> # Press a key
pinchtab hover [selector] # Hover an element
+pinchtab mouse move [selector] # Move the mouse to an element or coordinates
+pinchtab mouse down [selector] # Press a mouse button
+pinchtab mouse up [selector] # Release a mouse button
+pinchtab mouse wheel [selector] # Dispatch wheel deltas
pinchtab focus [selector] # Focus an element
pinchtab scroll <selector|pixels> # Scroll an element or the page
pinchtab select <selector> <value> # Select a <select> option
@@ -81,6 +85,16 @@ pinchtab uncheck <selector> # Uncheck a checkbox or radio
pinchtab scrollintoview <selector> # Scroll an element into view
```
+Low-level mouse commands are useful for drag handles, canvas-like UIs, and flows where DOM-native click or hover abstractions are not enough:
+
+```bash
+pinchtab mouse move e5
+pinchtab mouse down e5 --button left
+pinchtab mouse up e5 --button left
+pinchtab mouse wheel e5 --wheel-delta-y 240
+pinchtab mouse move --x 400 --y 320
+```
+
## Page Analysis
```bash
@@ -135,6 +149,16 @@ pinchtab cache clear # Clear browser HTTP disk cache
pinchtab cache status # Check if cache can be cleared
```
+Manual handoff and resume are API-only today:
+
+This is currently a temporary, non-blocking implementation. It records handoff state, but it does not yet enforce a hard stop on future automation requests by itself.
+
+```bash
+curl -X POST "$PINCHTAB_SERVER/tabs/<tabId>/handoff"
+curl "$PINCHTAB_SERVER/tabs/<tabId>/handoff"
+curl -X POST "$PINCHTAB_SERVER/tabs/<tabId>/resume"
+```
+
## Capture And Export
```bash
@@ -215,6 +239,10 @@ Commands with `--tab` currently include:
- `click`
- `dblclick`
- `hover`
+- `mouse move`
+- `mouse down`
+- `mouse up`
+- `mouse wheel`
- `focus`
- `type`
- `press`
diff --git a/docs/endpoints.md b/docs/endpoints.md
index 523b7f12..533980fd 100644
--- a/docs/endpoints.md
+++ b/docs/endpoints.md
@@ -73,6 +73,9 @@ GET /tabs
POST /tab
POST /tabs/{id}/close
GET /tabs/{id}/metrics
+POST /tabs/{id}/handoff
+GET /tabs/{id}/handoff
+POST /tabs/{id}/resume
```
Navigation request fields:
@@ -89,6 +92,24 @@ Important behavior:
- `POST /navigate` creates a new tab when `tabId` is omitted
- `POST /tab` supports `new`, `close`, and `focus`
+## Handoff And Manual Intervention
+
+```text
+POST /tabs/{id}/handoff
+GET /tabs/{id}/handoff
+POST /tabs/{id}/resume
+```
+
+Notes:
+
+- these routes are tab-scoped only
+- `POST /tabs/{id}/handoff` marks the tab as `paused_handoff` and records a reason
+- `GET /tabs/{id}/handoff` returns the current handoff state, or `active` when no handoff is set
+- `POST /tabs/{id}/resume` clears the handoff state and can carry resume metadata for the caller
+- current behavior is advisory only: handoff state is not yet a hard block on subsequent automation requests
+- treat the current implementation as temporary coordination state, not as a security boundary
+- there is currently no dedicated CLI wrapper for handoff or resume; use the HTTP API
+
## Tab Locking
```text
@@ -107,6 +128,8 @@ POST /actions
POST /macro
POST /tabs/{id}/action
POST /tabs/{id}/actions
+POST /wait
+POST /tabs/{id}/wait
GET /snapshot
GET /tabs/{id}/snapshot
GET /text
@@ -125,6 +148,10 @@ Action kinds currently include:
- `fill`
- `press`
- `hover`
+- `mousemove`
+- `mousedown`
+- `mouseup`
+- `mousewheel`
- `focus`
- `select`
- `scroll`
@@ -143,6 +170,10 @@ Action targeting fields:
- `selector`
- `nodeId`
- `x` and `y`
+- `button`
+- `wheelDeltaX` and `wheelDeltaY`
+- `waitNav`
+- `dialogAction` and `dialogText`
Snapshot query parameters:
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index 826ca073..5568529f 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -92,6 +92,10 @@ Common commands:
| `pinchtab quick <url>` | Navigate and snapshot |
| `pinchtab snap` | Accessibility snapshot |
| `pinchtab click <selector>` | Click an element |
+| `pinchtab mouse move <selector>` | Move the pointer to an element or coordinates |
+| `pinchtab mouse down <selector>` | Press a mouse button |
+| `pinchtab mouse up <selector>` | Release a mouse button |
+| `pinchtab mouse wheel <selector>` | Dispatch wheel deltas at an element or coordinates |
| `pinchtab type <selector> <text>` | Type via key events |
| `pinchtab fill <selector> <text>` | Fill directly |
| `pinchtab text` | Extract page text |
@@ -105,6 +109,20 @@ Common commands:
Many browser commands accept `--tab <id>` to target an existing tab instead of the active one.
+Manual handoff is currently API-only:
+
+This is currently advisory state only. It marks the tab as `paused_handoff`, but it does not yet provide a guaranteed blocking pause for later automation.
+
+```bash
+curl -X POST http://localhost:9867/tabs/<tabId>/handoff \
+ -H "Content-Type: application/json" \
+ -d '{"reason":"captcha"}'
+curl http://localhost:9867/tabs/<tabId>/handoff
+curl -X POST http://localhost:9867/tabs/<tabId>/resume \
+ -H "Content-Type: application/json" \
+ -d '{"status":"completed"}'
+```
+
## Tab Command
`pinchtab tab` is intentionally small:
diff --git a/docs/reference/handoff.md b/docs/reference/handoff.md
new file mode 100644
index 00000000..9a1dcb53
--- /dev/null
+++ b/docs/reference/handoff.md
@@ -0,0 +1,34 @@
+# Handoff
+
+Mark a tab for human intervention, inspect the handoff state, then resume automation when the manual step is complete.
+
+There is currently no dedicated CLI wrapper. Handoff is API-only.
+
+> Temporary status: the current handoff implementation is advisory only.
+> `POST /tabs/{id}/handoff` records `paused_handoff`, but it does not yet enforce a hard execution block across later automation requests.
+> Treat it as coordination metadata for now, not as a security boundary. A stricter blocking model tied to session-owned locks is expected later.
+
+```bash
+curl -X POST http://localhost:9867/tabs/<tabId>/handoff \
+ -H "Content-Type: application/json" \
+ -d '{"reason":"captcha","timeoutMs":120000}'
+
+curl http://localhost:9867/tabs/<tabId>/handoff
+
+curl -X POST http://localhost:9867/tabs/<tabId>/resume \
+ -H "Content-Type: application/json" \
+ -d '{"status":"completed","resolvedData":{"operator":"human"}}'
+```
+
+Notes:
+
+- `POST /tabs/{id}/handoff` sets the tab state to `paused_handoff`
+- `GET /tabs/{id}/handoff` returns the current handoff state, or `active` when no handoff is set
+- `POST /tabs/{id}/resume` clears the handoff state and can carry resume metadata such as `status` or `resolvedData`
+- today this is informational state only; it does not by itself block other later automation
+- use this for CAPTCHA, 2FA, login approval, or other human-only steps only if your caller also coordinates access separately
+
+## Related Pages
+
+- [Tabs](./tabs.md)
+- [CLI Overview](./cli.md)
diff --git a/docs/reference/index.md b/docs/reference/index.md
index c300210d..3237bf15 100644
--- a/docs/reference/index.md
+++ b/docs/reference/index.md
@@ -12,8 +12,10 @@ Note: this index is generated and should be checked against the code when comman
- [Find](./find.md)
- [Focus](./focus.md)
- [Health](./health.md)
+- [Handoff](./handoff.md)
- [Hover](./hover.md)
- [Instances](./instances.md)
+- [Mouse](./mouse.md)
- [Navigate](./navigate.md)
- [PDF](./pdf.md)
- [Press](./press.md)
diff --git a/docs/reference/mouse.md b/docs/reference/mouse.md
new file mode 100644
index 00000000..f5622123
--- /dev/null
+++ b/docs/reference/mouse.md
@@ -0,0 +1,40 @@
+# Mouse
+
+Low-level pointer controls for cases where DOM-native click or hover behavior is not enough.
+
+```bash
+curl -X POST http://localhost:9867/action \
+ -H "Content-Type: application/json" \
+ -d '{"kind":"mousemove","ref":"e5"}'
+
+curl -X POST http://localhost:9867/action \
+ -H "Content-Type: application/json" \
+ -d '{"kind":"mousedown","ref":"e5","button":"left"}'
+
+curl -X POST http://localhost:9867/action \
+ -H "Content-Type: application/json" \
+ -d '{"kind":"mouseup","ref":"e5","button":"left"}'
+
+curl -X POST http://localhost:9867/action \
+ -H "Content-Type: application/json" \
+ -d '{"kind":"mousewheel","x":400,"y":320,"wheelDeltaY":240}'
+
+# CLI Alternatives
+pinchtab mouse move e5
+pinchtab mouse down e5 --button left
+pinchtab mouse up e5 --button left
+pinchtab mouse wheel --x 400 --y 320 --wheel-delta-y 240
+```
+
+Notes:
+
+- mouse actions accept the same targeting modes as other action commands: `ref`, `selector`, `nodeId`, or `x`/`y`
+- `mousedown` and `mouseup` accept `button=left|right|middle`
+- `mousewheel` accepts `wheelDeltaX` and `wheelDeltaY`
+- use these for drag handles, canvas controls, precise hover choreography, or sites that require exact pointer sequencing
+
+## Related Pages
+
+- [Click](./click.md)
+- [Hover](./hover.md)
+- [Scroll](./scroll.md)
diff --git a/docs/reference/tabs.md b/docs/reference/tabs.md
index 003db277..e0519ccf 100644
--- a/docs/reference/tabs.md
+++ b/docs/reference/tabs.md
@@ -163,6 +163,47 @@ pinchtab wait --tab <tabId> 'text:Done'
pinchtab network --tab <tabId> --limit 20
```
+Low-level pointer control uses the same action surface:
+
+```bash
+curl -X POST http://localhost:9867/tabs/<tabId>/action \
+ -H "Content-Type: application/json" \
+ -d '{"kind":"mousemove","ref":"e5"}'
+
+curl -X POST http://localhost:9867/tabs/<tabId>/action \
+ -H "Content-Type: application/json" \
+ -d '{"kind":"mousedown","ref":"e5","button":"left"}'
+
+curl -X POST http://localhost:9867/tabs/<tabId>/action \
+ -H "Content-Type: application/json" \
+ -d '{"kind":"mousewheel","x":400,"y":320,"wheelDeltaY":240}'
+
+# CLI Alternatives
+pinchtab mouse move --tab <tabId> e5
+pinchtab mouse down --tab <tabId> e5 --button left
+pinchtab mouse wheel --tab <tabId> --x 400 --y 320 --wheel-delta-y 240
+```
+
+### Handoff State
+
+Human handoff is tab-scoped and API-only today.
+
+Current limitation: this is not a blocking pause yet. The tab is marked as `paused_handoff`, but normal automation is not universally rejected just because that state is present. Treat it as temporary coordination metadata, not as an enforced lockout.
+
+```bash
+curl -X POST http://localhost:9867/tabs/<tabId>/handoff \
+ -H "Content-Type: application/json" \
+ -d '{"reason":"captcha","timeoutMs":120000}'
+
+curl http://localhost:9867/tabs/<tabId>/handoff
+
+curl -X POST http://localhost:9867/tabs/<tabId>/resume \
+ -H "Content-Type: application/json" \
+ -d '{"status":"completed","resolvedData":{"operator":"human"}}'
+```
+
+Use this when automation must pause for a CAPTCHA, 2FA prompt, login approval, or another human-only step, but pair it with separate ownership/locking if you need hard exclusion today.
+
### Screenshot
```bash
@@ -219,3 +260,4 @@ There are also active-tab forms at `POST /lock` and `POST /unlock`.
- There is no `GET /tabs/{id}` endpoint for fetching single-tab metadata.
- `GET /tabs` and `GET /instances/tabs` serve different purposes and are not interchangeable.
- In the CLI, tab-scoped work happens through top-level commands with `--tab`, not through `pinchtab tab <subcommand>` variants.
+- There is no dedicated CLI `handoff` or `resume` command today.
diff --git a/internal/handlers/openapi.go b/internal/handlers/openapi.go
index 5ca3d873..a5868652 100644
--- a/internal/handlers/openapi.go
+++ b/internal/handlers/openapi.go
@@ -46,14 +46,14 @@ func (h *Handlers) HandleOpenAPI(w http.ResponseWriter, _ *http.Request) {
"/tabs": map[string]any{"get": map[string]any{"summary": "List tabs"}},
"/tabs/{id}/handoff": map[string]any{"post": map[string]any{"summary": "Pause tab automation for human handoff"}, "get": map[string]any{"summary": "Get tab handoff status"}},
"/tabs/{id}/resume": map[string]any{"post": map[string]any{"summary": "Resume tab automation after handoff"}},
- "/metrics": map[string]any{"get": map[string]any{"summary": "Runtime metrics"}},
- "/help": map[string]any{"get": map[string]any{"summary": "Alias for /openapi.json"}},
- "/text": map[string]any{"get": map[string]any{"summary": "Extract text", "parameters": []map[string]any{{"name": "maxChars", "in": "query", "schema": map[string]string{"type": "integer"}}, {"name": "format", "in": "query", "schema": map[string]string{"type": "string"}}}}},
- "/navigate": map[string]any{"post": map[string]any{"summary": "Navigate"}, "get": map[string]any{"summary": "Navigate (query params)"}},
- "/nav": map[string]any{"get": map[string]any{"summary": "Navigate alias"}},
- "/action": map[string]any{"post": map[string]any{"summary": "Single action"}, "get": map[string]any{"summary": "Single action (query params)"}},
- "/actions": map[string]any{"post": map[string]any{"summary": "Batch actions"}},
- "/snapshot": map[string]any{"get": map[string]any{"summary": "Accessibility snapshot"}},
+ "/metrics": map[string]any{"get": map[string]any{"summary": "Runtime metrics"}},
+ "/help": map[string]any{"get": map[string]any{"summary": "Alias for /openapi.json"}},
+ "/text": map[string]any{"get": map[string]any{"summary": "Extract text", "parameters": []map[string]any{{"name": "maxChars", "in": "query", "schema": map[string]string{"type": "integer"}}, {"name": "format", "in": "query", "schema": map[string]string{"type": "string"}}}}},
+ "/navigate": map[string]any{"post": map[string]any{"summary": "Navigate"}, "get": map[string]any{"summary": "Navigate (query params)"}},
+ "/nav": map[string]any{"get": map[string]any{"summary": "Navigate alias"}},
+ "/action": map[string]any{"post": map[string]any{"summary": "Single action"}, "get": map[string]any{"summary": "Single action (query params)"}},
+ "/actions": map[string]any{"post": map[string]any{"summary": "Batch actions"}},
+ "/snapshot": map[string]any{"get": map[string]any{"summary": "Accessibility snapshot"}},
"/evaluate": map[string]any{"post": map[string]any{
"summary": "Run JavaScript in the current tab",
"description": security["evaluate"].Message,
diff --git a/plugin/README.md b/plugin/README.md
index 59251b3d..c8a94142 100644
--- a/plugin/README.md
+++ b/plugin/README.md
@@ -110,6 +110,8 @@ pinchtab({ action: "mousewheel", x: 400, y: 300, wheelDeltaY: -320 })
Use `handoff` when manual intervention is required, then resume with a wait condition:
+Current limitation: this is advisory/non-blocking right now. The plugin uses `handoff` as coordination plus waiting behavior, but it does not guarantee that later automation is blocked across the server. Treat it as a temporary workflow helper, not as an enforced pause boundary.
+
```
1. pinchtab({ action: "handoff", humanReason: "captcha", humanPrompt: "Please solve CAPTCHA in headed browser" })
2. pinchtab({ action: "handoff", selector: "text:Dashboard", timeout: 120000 })
diff --git a/skills/pinchtab/SKILL.md b/skills/pinchtab/SKILL.md
index 6c986178..01af46f1 100644
--- a/skills/pinchtab/SKILL.md
+++ b/skills/pinchtab/SKILL.md
@@ -208,6 +208,10 @@ pinchtab click <selector> # Click element
pinchtab click --wait-nav <selector> # Click and wait for navigation
pinchtab click --x 100 --y 200 # Click by coordinates
pinchtab dblclick <selector> # Double-click element
+pinchtab mouse move <selector> # Move pointer to element center or coordinates
+pinchtab mouse down <selector> --button left # Press a mouse button
+pinchtab mouse up <selector> --button left # Release a mouse button
+pinchtab mouse wheel <selector> --wheel-delta-y 240 # Dispatch wheel deltas
pinchtab type <selector> <text> # Type with keystrokes
pinchtab fill <selector> <text> # Set value directly
pinchtab press <key> # Press key (Enter, Tab, Escape...)
@@ -221,6 +225,7 @@ Rules:
- Prefer `fill` for deterministic form entry.
- Prefer `type` only when the site depends on keystroke events.
- Prefer `click --wait-nav` when a click is expected to navigate.
+- Prefer low-level `mouse` commands only when normal `click` / `hover` abstractions are insufficient, such as drag handles, canvas widgets, or sites that depend on exact pointer sequences.
- Re-snapshot immediately after `click`, `press Enter`, `select`, or `scroll` if the UI can change.
- To discover valid dropdown values, snapshot with `filter=interactive` first — the output shows `<option>` elements with their `value` attributes. Then use `select` with the exact value.
- If a click opens a JS dialog (`alert`, `confirm`, `prompt`), pass `"dialogAction": "accept"` or `"dialogAction": "dismiss"` on the click action body. The dialog is auto-handled in a single call. Without this, the click hangs until `/tabs/TAB_ID/dialog` is called from a parallel request, and a pending dialog wedges subsequent `/snapshot` and `/text` calls.
@@ -314,6 +319,12 @@ curl -X POST http://localhost:9867/tabs/TAB_ID/action \
-H "Content-Type: application/json" \
-d '{"kind":"click","selector":"#submit-btn"}'
+# Low-level pointer action on a specific tab
+curl -X POST http://localhost:9867/tabs/TAB_ID/action \
+ -H "Authorization: Bearer <token>" \
+ -H "Content-Type: application/json" \
+ -d '{"kind":"mousewheel","x":400,"y":320,"wheelDeltaY":240}'
+
# Navigate back/forward in a specific tab
curl -X POST http://localhost:9867/tabs/TAB_ID/back \
-H "Authorization: Bearer <token>"
@@ -333,6 +344,23 @@ curl http://localhost:9867/tabs/TAB_ID/pdf \
# Close a tab
curl -X POST http://localhost:9867/tabs/TAB_ID/close \
-H "Authorization: Bearer <token>"
+
+# Pause automation for a human-only step
+curl -X POST http://localhost:9867/tabs/TAB_ID/handoff \
+ -H "Authorization: Bearer <token>" \
+ -H "Content-Type: application/json" \
+ -d '{"reason":"captcha","timeoutMs":120000}'
+
+# Inspect handoff status
+curl http://localhost:9867/tabs/TAB_ID/handoff \
+ -H "Authorization: Bearer <token>"
+
+# Resume automation after the human step is done
+curl -X POST http://localhost:9867/tabs/TAB_ID/resume \
+ -H "Authorization: Bearer <token>" \
+ -H "Content-Type: application/json" \
+ -d '{"status":"completed"}'
+
```
The default (non-tab-scoped) endpoints also support screenshots and PDF:
@@ -355,7 +383,7 @@ curl http://localhost:9867/pdf \
{"kind": "click", "selector": "#search-btn", "waitNav": true}
```
-All tab-scoped routes follow the pattern `/tabs/{TAB_ID}/...` and mirror the default endpoints. The full list includes: `navigate`, `back`, `forward`, `reload`, `snapshot`, `screenshot`, `text`, `pdf`, `action`, `actions`, `dialog`, `wait`, `find`, `lock`, `unlock`, `cookies`, `metrics`, `network`, `solve`, `close`, `storage`, `evaluate`, `download`, `upload`.
+All tab-scoped routes follow the pattern `/tabs/{TAB_ID}/...` and mirror the default endpoints. The full list includes: `navigate`, `back`, `forward`, `reload`, `snapshot`, `screenshot`, `text`, `pdf`, `action`, `actions`, `dialog`, `wait`, `find`, `lock`, `unlock`, `cookies`, `metrics`, `network`, `solve`, `close`, `storage`, `evaluate`, `download`, `upload`, `handoff`, and `resume`.
## Common Patterns
@@ -432,5 +460,3 @@ pinchtab click "xpath://button[@type='submit']"
- Profiles: [profiles.md](./references/profiles.md)
- MCP: [mcp.md](./references/mcp.md)
- Security model: [TRUST.md](./TRUST.md)
-
-
diff --git a/skills/pinchtab/references/api.md b/skills/pinchtab/references/api.md
index 2beb1f22..cab5b741 100644
--- a/skills/pinchtab/references/api.md
+++ b/skills/pinchtab/references/api.md
@@ -111,6 +111,22 @@ curl -X POST /action -H 'Content-Type: application/json' \
curl -X POST /action -H 'Content-Type: application/json' \
-d '{"kind": "hover", "ref": "e8"}'
+# Move pointer without clicking
+curl -X POST /action -H 'Content-Type: application/json' \
+ -d '{"kind": "mousemove", "ref": "e8"}'
+
+# Press and release a mouse button
+curl -X POST /action -H 'Content-Type: application/json' \
+ -d '{"kind": "mousedown", "ref": "e8", "button": "left"}'
+curl -X POST /action -H 'Content-Type: application/json' \
+ -d '{"kind": "mouseup", "ref": "e8", "button": "left"}'
+
+# Wheel at an element or coordinates
+curl -X POST /action -H 'Content-Type: application/json' \
+ -d '{"kind": "mousewheel", "ref": "e8", "wheelDeltaY": 240}'
+curl -X POST /action -H 'Content-Type: application/json' \
+ -d '{"kind": "mousewheel", "x": 400, "y": 320, "wheelDeltaY": -320}'
+
# Select dropdown option (by value or visible text)
curl -X POST /action -H 'Content-Type: application/json' \
-d '{"kind": "select", "ref": "e10", "value": "option2"}'
@@ -128,6 +144,30 @@ curl -X POST /action -H 'Content-Type: application/json' \
-d '{"kind": "click", "ref": "e5", "waitNav": true}'
```
+Notes:
+
+- selector-based click and double-click paths resolve through backend node IDs before dispatching pointer events
+- low-level pointer actions accept `ref`, `selector`, `nodeId`, or `x`/`y`
+- `mousedown` and `mouseup` accept `button` with `left`, `right`, or `middle`
+- `mousewheel` accepts `wheelDeltaX` and `wheelDeltaY`; when omitted, legacy `scrollX` / `scrollY` still work
+
+## Wait for page state
+
+```bash
+# CLI: pinchtab wait 'text:Done' / pinchtab wait --url '**/dashboard'
+curl -X POST /wait -H 'Content-Type: application/json' \
+ -d '{"selector":"text:Done","timeout":15000}'
+
+curl -X POST /wait -H 'Content-Type: application/json' \
+ -d '{"url":"**/dashboard","timeout":15000}'
+
+curl -X POST /wait -H 'Content-Type: application/json' \
+ -d '{"load":"networkidle","timeout":15000}'
+
+curl -X POST /wait -H 'Content-Type: application/json' \
+ -d '{"fn":"document.readyState === \"complete\"","timeout":15000}'
+```
+
## Batch actions
```bash
@@ -322,10 +362,28 @@ curl -X POST /tabs/TARGET_ID/action \
curl -X POST /tabs/TARGET_ID/actions \
-H 'Content-Type: application/json' \
-d '{"actions": [{"kind": "click", "ref": "e3"}, {"kind": "type", "ref": "e3", "text": "hello"}]}'
+
+# Wait on a specific tab
+curl -X POST /tabs/TARGET_ID/wait \
+ -H 'Content-Type: application/json' \
+ -d '{"selector":"text:Done","timeout":15000}'
+
+# Pause automation for manual intervention
+curl -X POST /tabs/TARGET_ID/handoff \
+ -H 'Content-Type: application/json' \
+ -d '{"reason":"captcha","timeoutMs":120000}'
+
+# Inspect or resume handoff state
+curl /tabs/TARGET_ID/handoff
+curl -X POST /tabs/TARGET_ID/resume \
+ -H 'Content-Type: application/json' \
+ -d '{"status":"completed"}'
```
These are equivalent to using `?tabId=TARGET_ID` on top-level endpoints but follow REST conventions. The tab ID comes from `/tabs` or from the `tabId` field in navigate/tab creation responses.
+`GET /tabs/{id}/handoff` returns the current status for that tab. `POST /tabs/{id}/resume` clears `paused_handoff` and can carry resume metadata such as `status` or `resolvedData`.
+
## Tab locking (multi-agent)
```bash
diff --git a/skills/pinchtab/references/commands.md b/skills/pinchtab/references/commands.md
index e9f77ce3..bd35eb69 100644
--- a/skills/pinchtab/references/commands.md
+++ b/skills/pinchtab/references/commands.md
@@ -93,6 +93,19 @@ pinchtab press Escape
### `pinchtab hover <ref>`
Hover over an element to trigger tooltips or hover styles.
+### `pinchtab mouse move|down|up|wheel [ref]`
+Low-level pointer controls for cases where DOM-native click or hover behavior is not enough.
+
+```bash
+pinchtab mouse move e5
+pinchtab mouse down e5 --button left
+pinchtab mouse up e5 --button left
+pinchtab mouse wheel e5 --wheel-delta-y 240
+pinchtab mouse move --x 400 --y 320
+```
+
+Use these for drag handles, canvas controls, precise hover choreography, or sites that require exact pointer sequencing.
+
### `pinchtab scroll [ref]`
Scroll the page or a specific element.
diff --git a/tests/e2e/fixtures/mouse-events.html b/tests/e2e/fixtures/mouse-events.html
new file mode 100644
index 00000000..6da7727d
--- /dev/null
+++ b/tests/e2e/fixtures/mouse-events.html
@@ -0,0 +1,136 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="UTF-8">
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
+ <title>E2E Test - Mouse Events</title>
+ <style>
+ body {
+ font-family: sans-serif;
+ margin: 0;
+ padding: 32px;
+ line-height: 1.4;
+ }
+
+ #mouse-target {
+ position: absolute;
+ left: 48px;
+ top: 140px;
+ width: 240px;
+ height: 140px;
+ border: 2px solid #2d6cdf;
+ border-radius: 12px;
+ background: #eef4ff;
+ color: #17315f;
+ font-size: 20px;
+ font-weight: 600;
+ cursor: pointer;
+ }
+
+ #summary {
+ margin-top: 320px;
+ display: grid;
+ grid-template-columns: repeat(3, minmax(120px, 1fr));
+ gap: 12px;
+ max-width: 720px;
+ }
+
+ .card {
+ padding: 12px;
+ border: 1px solid #d0d7e5;
+ border-radius: 10px;
+ background: #fafcff;
+ }
+
+ #state-json {
+ margin-top: 20px;
+ padding: 12px;
+ border-radius: 10px;
+ background: #111827;
+ color: #d1fae5;
+ white-space: pre-wrap;
+ max-width: 720px;
+ }
+ </style>
+</head>
+<body>
+ <h1>Mouse Events Fixture</h1>
+ <p>Use this page to verify low-level mouse actions update a visible event state.</p>
+
+ <button id="mouse-target" type="button">Mouse Target</button>
+
+ <section id="summary" aria-label="Mouse event summary">
+ <div class="card">Move count: <strong id="mousemove-count">0</strong></div>
+ <div class="card">Down count: <strong id="mousedown-count">0</strong></div>
+ <div class="card">Up count: <strong id="mouseup-count">0</strong></div>
+ <div class="card">Wheel count: <strong id="wheel-count">0</strong></div>
+ <div class="card">Last button: <strong id="last-button">none</strong></div>
+ <div class="card">Wheel Y total: <strong id="wheel-delta-y">0</strong></div>
+ </section>
+
+ <pre id="state-json" aria-live="polite"></pre>
+
+ <script>
+ const target = document.getElementById('mouse-target');
+ const stateEl = document.getElementById('state-json');
+
+ window.mouseFixtureState = {
+ mousemoveCount: 0,
+ mousedownCount: 0,
+ mouseupCount: 0,
+ wheelCount: 0,
+ lastButton: 'none',
+ wheelDeltaX: 0,
+ wheelDeltaY: 0,
+ lastClientX: 0,
+ lastClientY: 0,
+ sequence: []
+ };
+
+ function renderState() {
+ document.getElementById('mousemove-count').textContent = String(window.mouseFixtureState.mousemoveCount);
+ document.getElementById('mousedown-count').textContent = String(window.mouseFixtureState.mousedownCount);
+ document.getElementById('mouseup-count').textContent = String(window.mouseFixtureState.mouseupCount);
+ document.getElementById('wheel-count').textContent = String(window.mouseFixtureState.wheelCount);
+ document.getElementById('last-button').textContent = window.mouseFixtureState.lastButton;
+ document.getElementById('wheel-delta-y').textContent = String(window.mouseFixtureState.wheelDeltaY);
+ stateEl.textContent = JSON.stringify(window.mouseFixtureState, null, 2);
+ }
+
+ function record(type, event) {
+ window.mouseFixtureState.sequence.push(type);
+ if (window.mouseFixtureState.sequence.length > 12) {
+ window.mouseFixtureState.sequence.shift();
+ }
+ window.mouseFixtureState.lastClientX = Math.round(event.clientX || 0);
+ window.mouseFixtureState.lastClientY = Math.round(event.clientY || 0);
+
+ if (type === 'mousemove') {
+ window.mouseFixtureState.mousemoveCount += 1;
+ } else if (type === 'mousedown') {
+ window.mouseFixtureState.mousedownCount += 1;
+ window.mouseFixtureState.lastButton = event.button === 2 ? 'right' : event.button === 1 ? 'middle' : 'left';
+ } else if (type === 'mouseup') {
+ window.mouseFixtureState.mouseupCount += 1;
+ window.mouseFixtureState.lastButton = event.button === 2 ? 'right' : event.button === 1 ? 'middle' : 'left';
+ } else if (type === 'wheel') {
+ window.mouseFixtureState.wheelCount += 1;
+ window.mouseFixtureState.wheelDeltaX += Math.round(event.deltaX || 0);
+ window.mouseFixtureState.wheelDeltaY += Math.round(event.deltaY || 0);
+ }
+
+ renderState();
+ }
+
+ target.addEventListener('mousemove', (event) => record('mousemove', event));
+ target.addEventListener('mousedown', (event) => record('mousedown', event));
+ target.addEventListener('mouseup', (event) => record('mouseup', event));
+ target.addEventListener('wheel', (event) => {
+ event.preventDefault();
+ record('wheel', event);
+ }, { passive: false });
+
+ renderState();
+ </script>
+</body>
+</html>
diff --git a/tests/e2e/helpers/api-http.sh b/tests/e2e/helpers/api-http.sh
index c158e5ec..de4cfc73 100644
--- a/tests/e2e/helpers/api-http.sh
+++ b/tests/e2e/helpers/api-http.sh
@@ -221,6 +221,7 @@ assert_fixtures_accessible() {
assert_url_accessible "${FIXTURES_URL}/form.html" "fixtures/form.html"
assert_url_accessible "${FIXTURES_URL}/table.html" "fixtures/table.html"
assert_url_accessible "${FIXTURES_URL}/buttons.html" "fixtures/buttons.html"
+ assert_url_accessible "${FIXTURES_URL}/mouse-events.html" "fixtures/mouse-events.html"
}
assert_ok() {
diff --git a/tests/e2e/scenarios/api/actions-basic.sh b/tests/e2e/scenarios/api/actions-basic.sh
index 600a9ffd..b2aeb6ef 100644
--- a/tests/e2e/scenarios/api/actions-basic.sh
+++ b/tests/e2e/scenarios/api/actions-basic.sh
@@ -93,6 +93,55 @@ assert_ok "hover on button"
end_test
+# ─────────────────────────────────────────────────────────────────
+start_test "pinchtab low-level mouse actions"
+
+pt_post /navigate "{\"url\":\"${FIXTURES_URL}/mouse-events.html\"}"
+assert_ok "navigate"
+
+pt_get "/snapshot?filter=interactive"
+assert_ok "snapshot"
+REF=$(find_ref_by_name "Mouse Target")
+assert_ref_found "$REF" "mouse target ref"
+
+pt_post /action "{\"kind\":\"mousemove\",\"ref\":\"${REF}\"}"
+assert_ok "mousemove on target"
+
+pt_post /action "{\"kind\":\"mousedown\",\"ref\":\"${REF}\",\"button\":\"left\"}"
+assert_ok "mousedown on target"
+
+pt_post /action "{\"kind\":\"mouseup\",\"ref\":\"${REF}\",\"button\":\"left\"}"
+assert_ok "mouseup on target"
+
+pt_post /action '{"kind":"mousewheel","x":160,"y":190,"hasXY":true,"wheelDeltaY":240}'
+assert_ok "mousewheel on target coordinates"
+
+pt_post /evaluate '{"expression":"window.mouseFixtureState.mousemoveCount"}'
+assert_ok "evaluate mousemove count"
+assert_result_jq '.result >= 1' "mousemove count incremented" "mousemove count did not increment"
+
+pt_post /evaluate '{"expression":"window.mouseFixtureState.mousedownCount"}'
+assert_ok "evaluate mousedown count"
+assert_json_eq "$RESULT" '.result' '1' "mousedown count is 1"
+
+pt_post /evaluate '{"expression":"window.mouseFixtureState.mouseupCount"}'
+assert_ok "evaluate mouseup count"
+assert_json_eq "$RESULT" '.result' '1' "mouseup count is 1"
+
+pt_post /evaluate '{"expression":"window.mouseFixtureState.lastButton"}'
+assert_ok "evaluate last button"
+assert_json_eq "$RESULT" '.result' 'left' "last button is left"
+
+pt_post /evaluate '{"expression":"window.mouseFixtureState.wheelCount"}'
+assert_ok "evaluate wheel count"
+assert_json_eq "$RESULT" '.result' '1' "wheel count is 1"
+
+pt_post /evaluate '{"expression":"window.mouseFixtureState.wheelDeltaY"}'
+assert_ok "evaluate wheel delta"
+assert_json_eq "$RESULT" '.result' '240' "wheel delta Y accumulated"
+
+end_test
+
# ─────────────────────────────────────────────────────────────────
start_test "pinchtab focus (ref)"
diff --git a/tests/e2e/scenarios/cli/actions-basic.sh b/tests/e2e/scenarios/cli/actions-basic.sh
index 8ed426c8..c79de641 100644
--- a/tests/e2e/scenarios/cli/actions-basic.sh
+++ b/tests/e2e/scenarios/cli/actions-basic.sh
@@ -52,6 +52,47 @@ fi
end_test
+# ─────────────────────────────────────────────────────────────────
+start_test "pinchtab mouse move/down/up/wheel"
+
+pt_ok nav "${FIXTURES_URL}/mouse-events.html"
+pt_ok snap --interactive
+
+MOUSE_REF=$(find_ref_by_name "Mouse Target" "$PT_OUT")
+if assert_ref_found "$MOUSE_REF" "mouse target ref"; then
+ pt_ok mouse move "$MOUSE_REF"
+ assert_output_contains "moved" "confirms mouse move action"
+
+ pt_ok mouse down "$MOUSE_REF" --button left
+ assert_output_contains "down" "confirms mouse down action"
+
+ pt_ok mouse up "$MOUSE_REF" --button left
+ assert_output_contains "up" "confirms mouse up action"
+
+ pt_ok mouse wheel --x 160 --y 190 --wheel-delta-y 240
+ assert_output_contains "wheel" "confirms mouse wheel action"
+
+ pt_ok eval "window.mouseFixtureState.mousemoveCount"
+ assert_output_jq '.result >= 1' "mousemove count incremented" "mousemove count did not increment"
+
+ pt_ok eval "window.mouseFixtureState.mousedownCount"
+ assert_json_field ".result" "1" "mousedown count is 1"
+
+ pt_ok eval "window.mouseFixtureState.mouseupCount"
+ assert_json_field ".result" "1" "mouseup count is 1"
+
+ pt_ok eval "window.mouseFixtureState.lastButton"
+ assert_json_field ".result" "left" "last button is left"
+
+ pt_ok eval "window.mouseFixtureState.wheelCount"
+ assert_json_field ".result" "1" "wheel count is 1"
+
+ pt_ok eval "window.mouseFixtureState.wheelDeltaY"
+ assert_json_field ".result" "240" "wheel delta Y accumulated"
+fi
+
+end_test
+
# ─────────────────────────────────────────────────────────────────
start_test "pinchtab check/uncheck <selector>"
diff --git a/tests/e2e/scenarios/cli/actions-extended.sh b/tests/e2e/scenarios/cli/actions-extended.sh
index 893d2226..8481e934 100644
--- a/tests/e2e/scenarios/cli/actions-extended.sh
+++ b/tests/e2e/scenarios/cli/actions-extended.sh
@@ -54,7 +54,11 @@ start_test "pinchtab hover (basic)"
pt_ok nav "${FIXTURES_URL}/form.html"
pt_ok snap
-pt_ok hover e0
+
+HOVER_REF=$(find_ref_by_name "Username:" "$PT_OUT")
+if assert_ref_found "$HOVER_REF" "username input ref"; then
+ pt_ok hover "$HOVER_REF"
+fi
end_test