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.tsxindex 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.mdindex 8c1c5bfd..3201e51b 100644--- a/docs/commands.md+++ b/docs/commands.md@@ -73,6 +73,10 @@ pinchtab type <selector> <text> # Type via key eventspinchtab fill <selector> <text> # Fill directlypinchtab press <key> # Press a keypinchtab 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 deltaspinchtab focus [selector] # Focus an elementpinchtab scroll <selector|pixels> # Scroll an element or the pagepinchtab select <selector> <value> # Select a <select> option@@ -81,6 +85,16 @@ pinchtab uncheck <selector> # Uncheck a checkbox or radiopinchtab 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 cachepinchtab 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.mdindex 523b7f12..533980fd 100644--- a/docs/endpoints.md+++ b/docs/endpoints.md@@ -73,6 +73,9 @@ GET /tabsPOST /tabPOST /tabs/{id}/closeGET /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 /actionsPOST /macroPOST /tabs/{id}/actionPOST /tabs/{id}/actions+POST /wait+POST /tabs/{id}/waitGET /snapshotGET /tabs/{id}/snapshotGET /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.mdindex 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.mdnew file mode 100644index 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.mdindex 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.mdnew file mode 100644index 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.mdindex 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.goindex 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.mdindex 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.mdindex 6c986178..01af46f1 100644--- a/skills/pinchtab/SKILL.md+++ b/skills/pinchtab/SKILL.md@@ -208,6 +208,10 @@ pinchtab click <selector> # Click elementpinchtab click --wait-nav <selector> # Click and wait for navigationpinchtab click --x 100 --y 200 # Click by coordinatespinchtab 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 deltaspinchtab type <selector> <text> # Type with keystrokespinchtab fill <selector> <text> # Set value directlypinchtab 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 tabcurl -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 tabcurl -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.mdindex 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)```bashdiff --git a/skills/pinchtab/references/commands.md b/skills/pinchtab/references/commands.mdindex 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.htmlnew file mode 100644index 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.shindex 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.shindex 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.shindex 8ed426c8..c79de641 100644--- a/tests/e2e/scenarios/cli/actions-basic.sh+++ b/tests/e2e/scenarios/cli/actions-basic.sh@@ -52,6 +52,47 @@ fiend_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.shindex 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"+fiend_test