High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
feat: optimization of commands and move from json to natural language
Luigi Agosti7c36d27001f1
diff --git a/.gitignore b/.gitignoreindex c723c4a0..1eac2124 100644--- a/.gitignore+++ b/.gitignore@@ -52,4 +52,5 @@ pinchtab-smallpinchtab.exeplugins/*/.venv/tests/e2e/results/*-runner\ No newline at end of file+runner+skills/agent-browser\ No newline at end of filediff --git a/cmd/pinchtab/cmd_cli_browser_actions.go b/cmd/pinchtab/cmd_cli_browser_actions.goindex b88d00d3..c6a90680 100644--- a/cmd/pinchtab/cmd_cli_browser_actions.go+++ b/cmd/pinchtab/cmd_cli_browser_actions.go@@ -169,7 +169,7 @@ var dialogAcceptCmd = &cobra.Command{Args: cobra.MaximumNArgs(1),Run: func(cmd *cobra.Command, args []string) {runCLI(func(rt cliRuntime) {- browseractions.Dialog(rt.client, rt.base, rt.token, "accept", optionalArg(args), stringFlag(cmd, "tab"))+ browseractions.Dialog(rt.client, rt.base, rt.token, "accept", optionalArg(args), cmd)})},}@@ -179,7 +179,7 @@ var dialogDismissCmd = &cobra.Command{Short: "Dismiss (Cancel) the current dialog",Run: func(cmd *cobra.Command, args []string) {runCLI(func(rt cliRuntime) {- browseractions.Dialog(rt.client, rt.base, rt.token, "dismiss", "", stringFlag(cmd, "tab"))+ browseractions.Dialog(rt.client, rt.base, rt.token, "dismiss", "", cmd)})},}diff --git a/cmd/pinchtab/cmd_cli_browser_nav.go b/cmd/pinchtab/cmd_cli_browser_nav.goindex 61a10953..3bc30c7c 100644--- a/cmd/pinchtab/cmd_cli_browser_nav.go+++ b/cmd/pinchtab/cmd_cli_browser_nav.go@@ -26,7 +26,8 @@ var navCmd = &cobra.Command{Run: func(cmd *cobra.Command, args []string) {url := urls.Normalize(args[0])runCLI(func(rt cliRuntime) {- browseractions.Navigate(rt.client, rt.base, rt.token, url, cmd)+ tabID := browseractions.Navigate(rt.client, rt.base, rt.token, url, cmd)+ WriteTabStateFile(tabID)})},}@@ -69,10 +70,10 @@ var tabsCmd = &cobra.Command{Run: func(cmd *cobra.Command, args []string) {runCLI(func(rt cliRuntime) {if len(args) == 0 {- browseractions.TabList(rt.client, rt.base, rt.token)+ browseractions.TabList(rt.client, rt.base, rt.token, cmd)return}- browseractions.TabFocus(rt.client, rt.base, rt.token, args[0])+ browseractions.TabFocus(rt.client, rt.base, rt.token, args[0], cmd)})},}@@ -87,7 +88,7 @@ var tabNewCmd = &cobra.Command{if len(args) > 0 {body["url"] = urls.Normalize(args[0])}- browseractions.TabNew(rt.client, rt.base, rt.token, body)+ browseractions.TabNew(rt.client, rt.base, rt.token, body, cmd)})},}@@ -98,7 +99,7 @@ var tabCloseCmd = &cobra.Command{Args: cobra.ExactArgs(1),Run: func(cmd *cobra.Command, args []string) {runCLI(func(rt cliRuntime) {- browseractions.TabClose(rt.client, rt.base, rt.token, args[0])+ browseractions.TabClose(rt.client, rt.base, rt.token, args[0], cmd)})},}diff --git a/cmd/pinchtab/cmd_cli_management.go b/cmd/pinchtab/cmd_cli_management.goindex 285a102c..ec272404 100644--- a/cmd/pinchtab/cmd_cli_management.go+++ b/cmd/pinchtab/cmd_cli_management.go@@ -21,7 +21,7 @@ var healthCmd = &cobra.Command{Short: "Check server health",Run: func(cmd *cobra.Command, args []string) {runCLI(func(rt cliRuntime) {- browseractions.Health(rt.client, rt.base, rt.token)+ browseractions.Health(rt.client, rt.base, rt.token, cmd)})},}diff --git a/cmd/pinchtab/cmd_cli_register.go b/cmd/pinchtab/cmd_cli_register.goindex a68977be..9aa247b8 100644--- a/cmd/pinchtab/cmd_cli_register.go+++ b/cmd/pinchtab/cmd_cli_register.go@@ -2,6 +2,8 @@ package mainimport ("os"+ "path/filepath"+ "strings""github.com/pinchtab/pinchtab/internal/bridge""github.com/spf13/cobra"@@ -128,6 +130,9 @@ func configureBrowserFlags() {clickCmd.Flags().String("css", "", "CSS selector instead of ref")addPointFlags(clickCmd, "click")clickCmd.Flags().Bool("wait-nav", false, "Wait for navigation after click")+ clickCmd.Flags().Bool("snap", false, "Output interactive snapshot after action")+ clickCmd.Flags().Bool("snap-diff", false, "Output snapshot diff after action (changes only)")+ clickCmd.Flags().Bool("text", false, "Output page text after action (for verification)")clickCmd.Flags().String("dialog-action", "", "Auto-handle a JS dialog opened by the click: accept | dismiss")clickCmd.Flags().String("dialog-text", "", "Prompt response text (with --dialog-action accept on prompt())")@@ -159,8 +164,9 @@ func configureBrowserFlags() {focusCmd.Flags().String("css", "", "CSS selector instead of ref")- snapCmd.Flags().BoolP("interactive", "i", false, "Filter interactive elements only")- snapCmd.Flags().BoolP("compact", "c", false, "Compact output format")+ snapCmd.Flags().BoolP("interactive", "i", true, "Filter interactive elements + headings (default true, use --interactive=false for all)")+ snapCmd.Flags().BoolP("compact", "c", true, "Compact output format (default true, use --compact=false for JSON)")+ snapCmd.Flags().Bool("full", false, "Full JSON output (shorthand for --interactive=false --compact=false)")snapCmd.Flags().Bool("text", false, "Text output format")snapCmd.Flags().BoolP("diff", "d", false, "Show diff from previous snapshot")snapCmd.Flags().StringP("selector", "s", "", "CSS selector to scope snapshot")@@ -199,10 +205,31 @@ func configureBrowserFlags() {textCmd.Flags().Bool("full", false, "Return the full page text (document.body.innerText) instead of the default Readability-filtered content")textCmd.Flags().String("frame", "", "Extract text from a specific iframe by frameId. If unset, uses the tab's active frame scope (set via `pinchtab frame`) or the top-level document.")textCmd.Flags().StringP("selector", "s", "", "Element selector to extract text from (ref/CSS/XPath/text)")+ textCmd.Flags().Bool("json", false, "Output full JSON response instead of just text content")navCmd.Flags().Bool("new-tab", false, "Open in new tab")navCmd.Flags().Bool("block-images", false, "Block image loading")navCmd.Flags().Bool("block-ads", false, "Block ads")+ navCmd.Flags().Bool("snap", false, "Output interactive snapshot after navigation")+ navCmd.Flags().Bool("snap-diff", false, "Output snapshot diff after navigation (changes only)")++ backCmd.Flags().Bool("snap", false, "Output interactive snapshot after navigation")+ backCmd.Flags().Bool("snap-diff", false, "Output snapshot diff after navigation (changes only)")+ backCmd.Flags().Bool("text", false, "Output page text after navigation (for verification)")+ forwardCmd.Flags().Bool("snap", false, "Output interactive snapshot after navigation")+ forwardCmd.Flags().Bool("snap-diff", false, "Output snapshot diff after navigation (changes only)")+ forwardCmd.Flags().Bool("text", false, "Output page text after navigation (for verification)")+ reloadCmd.Flags().Bool("snap", false, "Output interactive snapshot after reload")+ reloadCmd.Flags().Bool("snap-diff", false, "Output snapshot diff after reload (changes only)")+ reloadCmd.Flags().Bool("text", false, "Output page text after reload (for verification)")+ fillCmd.Flags().Bool("snap", false, "Output interactive snapshot after fill")+ fillCmd.Flags().Bool("snap-diff", false, "Output snapshot diff after fill (changes only)")+ fillCmd.Flags().Bool("text", false, "Output page text after fill (for verification)")+ selectCmd.Flags().Bool("snap", false, "Output interactive snapshot after select")+ selectCmd.Flags().Bool("snap-diff", false, "Output snapshot diff after select (changes only)")+ selectCmd.Flags().Bool("text", false, "Output page text after select (for verification)")+ scrollCmd.Flags().Bool("snap", false, "Output interactive snapshot after scroll")+ scrollCmd.Flags().Bool("snap-diff", false, "Output snapshot diff after scroll (changes only)")addTabFlag(navCmd,@@ -246,6 +273,42 @@ func configureBrowserFlags() {evalCmd.Flags().Bool("await-promise", false, "Resolve a returned Promise before responding")navCmd.Flags().Bool("print-tab-id", false, "Print only the tab ID on stdout (also triggered automatically when stdout is a pipe)")+ // Add --json flag to action commands (default is terse output)+ addJSONFlag(+ clickCmd,+ dblclickCmd,+ hoverCmd,+ mouseMoveCmd,+ mouseDownCmd,+ mouseUpCmd,+ mouseWheelCmd,+ dragCmd,+ focusCmd,+ typeCmd,+ pressCmd,+ fillCmd,+ scrollCmd,+ selectCmd,+ checkCmd,+ uncheckCmd,+ scrollintoviewCmd,+ waitCmd,+ dialogAcceptCmd,+ dialogDismissCmd,+ backCmd,+ forwardCmd,+ reloadCmd,+ navCmd,+ findCmd,+ evalCmd,+ tabsCmd,+ tabNewCmd,+ tabCloseCmd,+ healthCmd,+ cacheClearCmd,+ cacheStatusCmd,+ )+scrollintoviewCmd.Flags().String("css", "", "CSS selector instead of ref")networkCmd.Flags().String("filter", "", "URL pattern filter")@@ -296,21 +359,61 @@ func addRootCommands(cmds ...*cobra.Command) {}// addTabFlag wires a --tab flag onto the given commands and defaults its-// value to $PINCHTAB_TAB when the env var is set. This lets agents avoid-// threading `--tab "$TAB"` through every command:+// value from (in priority order): $PINCHTAB_TAB env var, or the state file+// written by `nav`. This lets agents avoid threading `--tab "$TAB"` through+// every command://-// export PINCHTAB_TAB=$(pinchtab nav http://example.com)-// pinchtab snap -i -c # auto-targets $PINCHTAB_TAB+// pinchtab nav http://example.com # writes tab ID to state file+// pinchtab snap -i -c # auto-reads from state file//-// Explicit --tab still wins (cobra flag precedence). If the env var isn't-// set and no flag is passed, the server picks the active tab as before.+// Explicit --tab still wins (cobra flag precedence). If neither env var nor+// state file is set, the server picks the active tab as before.func addTabFlag(cmds ...*cobra.Command) {defaultTab := os.Getenv("PINCHTAB_TAB")+ if defaultTab == "" {+ defaultTab = readTabStateFile()+ }for _, cmd := range cmds {cmd.Flags().String("tab", defaultTab, "Tab ID (env: PINCHTAB_TAB)")}}+// tabStateFile returns the path to the tab state file.+func tabStateFile() string {+ if dir := os.Getenv("XDG_STATE_HOME"); dir != "" {+ return dir + "/pinchtab/current-tab"+ }+ if home, err := os.UserHomeDir(); err == nil {+ return home + "/.local/state/pinchtab/current-tab"+ }+ return "/tmp/pinchtab-current-tab"+}++// readTabStateFile reads the persisted tab ID from the state file.+func readTabStateFile() string {+ data, err := os.ReadFile(tabStateFile())+ if err != nil {+ return ""+ }+ return strings.TrimSpace(string(data))+}++// WriteTabStateFile persists the tab ID to the state file for subsequent commands.+func WriteTabStateFile(tabID string) {+ if tabID == "" {+ return+ }+ path := tabStateFile()+ _ = os.MkdirAll(filepath.Dir(path), 0755)+ _ = os.WriteFile(path, []byte(tabID+"\n"), 0644)+}++func addJSONFlag(cmds ...*cobra.Command) {+ for _, cmd := range cmds {+ cmd.Flags().Bool("json", false, "Output full JSON response instead of terse status")+ }+}+func addPointFlags(cmd *cobra.Command, action string) {cmd.Flags().Float64("x", 0, "X coordinate for "+action)cmd.Flags().Float64("y", 0, "Y coordinate for "+action)diff --git a/docs/commands.md b/docs/commands.mdindex 2fd14fab..71b834c2 100644--- a/docs/commands.md+++ b/docs/commands.md@@ -25,6 +25,7 @@ pinchtab nav <url> --tab <id> # Reuse a specific tabpinchtab nav <url> --new-tab # Explicitly force a new tabpinchtab nav <url> --block-images # Block images for this navigationpinchtab nav <url> --block-ads # Block ads for this navigation+pinchtab nav <url> --snap # Navigate and output interactive snapshotpinchtab quick <url> # Navigate and take a snapshotpinchtab back # Go back in the active tabpinchtab back --tab <id> # Go back in a specific tab@@ -73,6 +74,7 @@ pinchtab frame main # Return selector scope to the top documepinchtab click [selector] # Click an element or coordinates with --x/--ypinchtab click --css <selector> # Force CSS selector modepinchtab click --wait-nav <selector> # Click and wait for navigation+pinchtab click --snap <selector> # Click and output interactive snapshotpinchtab dblclick [selector] # Double-clickpinchtab type <selector> <text> # Type via key eventspinchtab fill <selector> <text> # Fill directly@@ -86,6 +88,8 @@ pinchtab mouse wheel [dy|selector] # Dispatch wheel deltaspinchtab drag <from> <to> # Drag between targets (selector/ref or x,y)pinchtab focus [selector] # Focus an elementpinchtab scroll <selector|pixels> # Scroll an element or the page+pinchtab scroll down --snap # Scroll and output snapshot+pinchtab scroll 800 --snap-diff # Scroll and output snapshot diffpinchtab select <selector> <value> # Select a <select> optionpinchtab check <selector> # Check a checkbox or radiopinchtab uncheck <selector> # Uncheck a checkbox or radiodiff --git a/docs/deep-dive/benchmark.md b/docs/deep-dive/benchmark.mdindex 4eb79447..8dfbb1c0 100644--- a/docs/deep-dive/benchmark.md+++ b/docs/deep-dive/benchmark.md@@ -1,14 +1,38 @@# Benchmark: Deep DiveThis document compares two agent-driven browser surfaces — **PinchTab** and-**agent-browser** — on the same 10-step benchmark task set, driven by-`claude-haiku-4-5-20251001` through our API runner. The goal is to measure the-real, end-to-end token cost of using each tool with an LLM agent, not an-abstract "tool cost".--The numbers below come from ten fresh runs recorded on 2026-04-20:-`lp1`–`lp5` (PinchTab lane) and `la1`–`la5` (agent-browser lane). Raw logs-are attached at the bottom of this document.+**agent-browser** — on a shared benchmark task set, driven through our API+runner. The goal is to measure the real, end-to-end token cost of using+each tool with an LLM agent, not an abstract "tool cost".++The primary anchor is a 10-step basic-scope comparison on+`claude-haiku-4-5-20251001` with n=5 per lane (`lp1`–`lp5`, `la1`–`la5`).+It is supplemented by a 24-step extended-scope comparison on the same+model (n=3 per lane, `lpe1`–`lpe3` / `lae1`–`lae3`) and a 24-step+extended-scope comparison on `claude-sonnet-4-6` (n=2 per lane,+`lpe-sonnet46-*` / `lae*-sonnet46-*`). All numbers were recorded on+2026-04-20. Raw logs are attached at the bottom of this document.++## TL;DR++PinchTab is cheaper and uses fewer API round trips than agent-browser on+every scope we measured. Percentages below are *relative to agent-browser*+(i.e. "PinchTab is N% cheaper than agent-browser on this metric").++| Scope | Model | n | PinchTab cost | agent-browser cost | PinchTab cheaper | Fewer requests | Fewer tokens |+|-------|-------|--:|--------------:|-------------------:|-----------------:|---------------:|-------------:|+| Basic (10 steps) | Haiku 4.5 | 5 | $0.1024 | $0.1132 | **9.5%** | 23.0% | 17.9% |+| Extended (24 steps) | Haiku 4.5 | 3 | $0.3516 | $0.4372 | **19.6%** | 31.1% | 26.2% |+| Extended (24 steps) | Sonnet 4.6 | 2 | $0.8932 | $1.1204 | **20.3%** | 29.4% | 25.3% |++- **The cost gap widens at longer scope** (9.5% → 19.6% on Haiku). The+ click→snapshot round trip compounds with step count.+- **The lane gap is roughly model-invariant at extended scope** (Haiku+ 19.6%, Sonnet 20.3%). A stronger model doesn't reason its way around+ the extra round trip.+- **Requests fall more than tokens fall more than cost falls.** Most of+ agent-browser's extra tokens are `cache_read` at $0.10/1M (Haiku) or+ $0.30/1M (Sonnet) — cheap per token but many of them.## How the Test is Conducted@@ -20,7 +44,7 @@ lane-specific task overrides.### Environment-Every run is executed inside Docker Compose (`tests/tools/docker/compose.yml`)+Every run is executed inside Docker Compose (`tests/tools/docker-compose.yml`)with three services:- `fixtures` — the benchmark web server hosting the test pages@@ -103,40 +127,24 @@ All ten runs scored 10/10 passes on the same 10-step set. Anthropic### Raw per-run totals-| Run | Requests | Uncached input | Cache create | Cache read | Output | Total tokens |-|-----|---------:|---------------:|-------------:|-----------:|-------:|-------------:|-| lp1 | 33 | 68,028 | 6,232 | 199,424 | 4,008 | 277,692 |-| lp2 | 27 | 47,287 | 6,232 | 162,032 | 3,385 | 218,936 |-| lp3 | 31 | 55,872 | 6,232 | 186,960 | 3,991 | 253,055 |-| lp4 | 28 | 57,958 | 6,232 | 168,264 | 3,659 | 236,113 |-| lp5 | 32 | 56,603 | 6,232 | 193,192 | 4,217 | 260,244 |-| **lp avg** | **30.2** | **57,150** | **6,232** | **181,974** | **3,852** | **249,208** |-| la1 | 38 | 57,162 | 6,047 | 223,739 | 4,358 | 291,306 |-| la2 | 36 | 52,276 | 6,047 | 217,692 | 4,308 | 280,323 |-| la3 | 46 | 74,104 | 6,047 | 272,115 | 5,305 | 357,571 |-| la4 | 38 | 57,352 | 6,047 | 229,786 | 4,372 | 297,557 |-| la5 | 38 | 57,188 | 6,047 | 223,739 | 4,337 | 291,311 |-| **la avg** | **39.2** | **59,616** | **6,047** | **233,414** | **4,536** | **303,614** |--### Cost (Anthropic Haiku 4.5, 2026-04-20 pricing)--Pricing per 1M tokens: `$1.00` uncached input, `$1.25` cache-create (1.25×),-`$0.10` cache-read (0.1×), `$5.00` output (5×).--| Run | Cost |-|-----|-----:|-| lp1 | $0.1158 |-| lp2 | $0.0882 |-| lp3 | $0.1023 |-| lp4 | $0.1009 |-| lp5 | $0.1048 |-| **lp avg** | **$0.1024** |-| la1 | $0.1089 |-| la2 | $0.1031 |-| la3 | $0.1354 |-| la4 | $0.1097 |-| la5 | $0.1088 |-| **la avg** | **$0.1132** |+Pricing per 1M tokens (Anthropic Haiku 4.5, 2026-04-20): `$1.00` uncached+input, `$1.25` cache-create (1.25×), `$0.10` cache-read (0.1×), `$5.00`+output (5×).++| Run | Requests | Uncached input | Cache create | Cache read | Output | Total tokens | Cost |+|-----|---------:|---------------:|-------------:|-----------:|-------:|-------------:|-----:|+| lp1 | 33 | 68,028 | 6,232 | 199,424 | 4,008 | 277,692 | $0.1158 |+| lp2 | 27 | 47,287 | 6,232 | 162,032 | 3,385 | 218,936 | $0.0882 |+| lp3 | 31 | 55,872 | 6,232 | 186,960 | 3,991 | 253,055 | $0.1023 |+| lp4 | 28 | 57,958 | 6,232 | 168,264 | 3,659 | 236,113 | $0.1009 |+| lp5 | 32 | 56,603 | 6,232 | 193,192 | 4,217 | 260,244 | $0.1048 |+| **lp avg** | **30.2** | **57,150** | **6,232** | **181,974** | **3,852** | **249,208** | **$0.1024** |+| la1 | 38 | 57,162 | 6,047 | 223,739 | 4,358 | 291,306 | $0.1089 |+| la2 | 36 | 52,276 | 6,047 | 217,692 | 4,308 | 280,323 | $0.1031 |+| la3 | 46 | 74,104 | 6,047 | 272,115 | 5,305 | 357,571 | $0.1354 |+| la4 | 38 | 57,352 | 6,047 | 229,786 | 4,372 | 297,557 | $0.1097 |+| la5 | 38 | 57,188 | 6,047 | 223,739 | 4,337 | 291,311 | $0.1088 |+| **la avg** | **39.2** | **59,616** | **6,047** | **233,414** | **4,536** | **303,614** | **$0.1132** |### Averages (the comparison)@@ -144,21 +152,21 @@ Pricing per 1M tokens: `$1.00` uncached input, `$1.25` cache-create (1.25×),|------|-------------:|-------------------:|-----------------:|---------------:|-----------:|-----------------:|---------:|| PinchTab (lp1–lp5) | **30.2** | 57,150 | 6,232 | 181,974 | 3,852 | **249,208** | **$0.1024** || agent-browser (la1–la5) | **39.2** | 59,616 | 6,047 | 233,414 | 4,536 | **303,614** | **$0.1132** |-| Δ (la − lp) | +9.0 | +2,466 | −185 | **+51,440** | +684 | +54,406 | +$0.0108 |-| Δ (% vs lp) | +30% | +4% | −3% | **+28%** | +18% | +22% | **+10.5%** |+| Δ (lp − la) | −9.0 | −2,466 | +185 | **−51,440** | −684 | −54,406 | −$0.0108 |+| PinchTab cheaper (% vs la) | **23.0%** | 4.1% | −3.1% | **22.0%** | 15.1% | **17.9%** | **9.5%** |**Per-run averages:**-- PinchTab is **~10% cheaper** per run on cost ($0.1024 vs $0.1132).-- PinchTab uses **~30% fewer API requests** (30.2 vs 39.2).-- PinchTab's total tokens are **~22% lower** on average, driven almost- entirely by **cache-read** (+51k on la) — the click→snapshot ping-pong- inflates re-reads of the cached prefix.+- PinchTab is **~9.5% cheaper** per run on cost ($0.1024 vs $0.1132).+- PinchTab uses **~23% fewer API requests** (30.2 vs 39.2).+- PinchTab's total tokens are **~18% lower** on average, driven almost+ entirely by **cache-read** (−51k on lp) — the click→snapshot ping-pong+ inflates re-reads of the cached prefix on agent-browser.**Per-step** (10 steps per run): PinchTab $0.01024/step, agent-browser$0.01132/step.-The token gap (~22%) is bigger than the dollar gap (~10%) because most of+The token gap (~18%) is bigger than the dollar gap (~9.5%) because most ofagent-browser's extra tokens are `cache_read` at $0.10/1M — cheap per tokenbut many of them due to the click→snapshot pattern.@@ -167,7 +175,7 @@ but many of them due to the click→snapshot pattern.- **PinchTab** spread: $0.0882 → $0.1158 (~$0.028, 31% of mean).- **agent-browser** spread: $0.1031 → $0.1354 (~$0.032, 29% of mean),dominated by run 3 (46 requests, $0.1354). Without la3 the la mean drops- to $0.1076 and the gap narrows to ~5%.+ to $0.1076 and PinchTab's cost advantage narrows to ~5%.Variance is still high enough that single-run conclusions should betreated with caution; n=5 gives a usable central tendency but the@@ -175,7 +183,7 @@ confidence interval is wide.## Extended Scope: 2026-04-20 runs (n=3 each, 24 steps)-To check whether the ~10% basic-scope gap holds up at longer workloads, we+To check whether the ~9.5% basic-scope advantage holds up at longer workloads, were-ran both lanes against **6 groups (0, 1, 2, 3, 4, 5)** — 24 steps perrun — with `--max-turns 250`. Three runs per lane, same model(`claude-haiku-4-5-20251001`). Logs prefixed `lae*` (agent-browser) and@@ -183,29 +191,18 @@ run — with `--max-turns 250`. Three runs per lane, same model### Raw per-run totals-| Run | Requests | Uncached input | Cache create | Cache read | Output | Total tokens | Answered | Passed | Pass rate |-|-----|---------:|---------------:|-------------:|-----------:|-------:|-------------:|---------:|-------:|----------:|-| lpe1 | 97 | 225,185 | 7,074 | 679,104 | 12,574 | 923,937 | 24 | 23 | 95.8% |-| lpe2 | 89 | 200,720 | 7,074 | 622,512 | 11,431 | 841,737 | 24 | 24 | 100% |-| lpe3 | 91 | 224,544 | 7,074 | 636,660 | 12,780 | 881,058 | 24 | 24 | 100% |-| **lpe avg** | **92.3** | **216,816** | **7,074** | **646,092** | **12,262** | **882,244** | **24.0** | **23.7** | **98.6%** |-| lae1 | 130 | 240,784 | 6,873 | 886,617 | 15,181 | 1,149,455 | 23 | 22 | 95.6% |-| lae2 | 112 | 231,525 | 6,873 | 762,903 | 13,605 | 1,014,906 | 24 | 24 | 100% |-| lae3 | 160 | 303,182 | 6,873 | 1,092,807 | 18,427 | 1,421,289 | 24 | 24 | 100% |-| **lae avg** | **134.0** | **258,497** | **6,873** | **914,109** | **15,738** | **1,195,217** | **23.7** | **23.3** | **98.5%** |--### Cost--| Run | Cost |-|-----|-----:|-| lpe1 | $0.3648 |-| lpe2 | $0.3290 |-| lpe3 | $0.3610 |-| **lpe avg** | **$0.3516** |-| lae1 | $0.4139 |-| lae2 | $0.3844 |-| lae3 | $0.5132 |-| **lae avg** | **$0.4372** |+Same Haiku 4.5 pricing as the basic scope above.++| Run | Requests | Uncached input | Cache create | Cache read | Output | Total tokens | Answered | Passed | Pass rate | Cost |+|-----|---------:|---------------:|-------------:|-----------:|-------:|-------------:|---------:|-------:|----------:|-----:|+| lpe1 | 97 | 225,185 | 7,074 | 679,104 | 12,574 | 923,937 | 24 | 23 | 95.8% | $0.3648 |+| lpe2 | 89 | 200,720 | 7,074 | 622,512 | 11,431 | 841,737 | 24 | 24 | 100% | $0.3290 |+| lpe3 | 91 | 224,544 | 7,074 | 636,660 | 12,780 | 881,058 | 24 | 24 | 100% | $0.3610 |+| **lpe avg** | **92.3** | **216,816** | **7,074** | **646,092** | **12,262** | **882,244** | **24.0** | **23.7** | **98.6%** | **$0.3516** |+| lae1 | 130 | 240,784 | 6,873 | 886,617 | 15,181 | 1,149,455 | 23 | 22 | 95.6% | $0.4139 |+| lae2 | 112 | 231,525 | 6,873 | 762,903 | 13,605 | 1,014,906 | 24 | 24 | 100% | $0.3844 |+| lae3 | 160 | 303,182 | 6,873 | 1,092,807 | 18,427 | 1,421,289 | 24 | 24 | 100% | $0.5132 |+| **lae avg** | **134.0** | **258,497** | **6,873** | **914,109** | **15,738** | **1,195,217** | **23.7** | **23.3** | **98.5%** | **$0.4372** |### Averages (the comparison)@@ -213,19 +210,19 @@ run — with `--max-turns 250`. Three runs per lane, same model|------|-------------:|-------------------:|-----------------:|---------------:|-----------:|-----------------:|---------:|| PinchTab (lpe1–lpe3) | **92.3** | 216,816 | 7,074 | 646,092 | 12,262 | **882,244** | **$0.3516** || agent-browser (lae1–lae3) | **134.0** | 258,497 | 6,873 | 914,109 | 15,738 | **1,195,217** | **$0.4372** |-| Δ (lae − lpe) | +41.7 | +41,681 | −201 | **+268,017** | +3,476 | +312,973 | +$0.0856 |-| Δ (% vs lpe) | +45% | +19% | −3% | **+41%** | +28% | +35% | **+24.4%** |+| Δ (lpe − lae) | −41.7 | −41,681 | +201 | **−268,017** | −3,476 | −312,973 | −$0.0856 |+| PinchTab cheaper (% vs lae) | **31.1%** | 16.1% | −2.9% | **29.3%** | 22.1% | **26.2%** | **19.6%** |**Per-run averages:**-- PinchTab is **~24% cheaper** per run on cost ($0.3516 vs $0.4372).-- PinchTab uses **~45% fewer API requests** (92.3 vs 134.0).-- PinchTab's total tokens are **~35% lower** on average, again dominated- by **cache-read** (+268k on lae) as the click→snapshot pattern compounds- with more steps.+- PinchTab is **~19.6% cheaper** per run on cost ($0.3516 vs $0.4372).+- PinchTab uses **~31% fewer API requests** (92.3 vs 134.0).+- PinchTab's total tokens are **~26% lower** on average, again dominated+ by **cache-read** (−268k on lpe) as the click→snapshot pattern compounds+ with more steps on agent-browser.**Per-step** (24 steps per run): PinchTab $0.01465/step, agent-browser-$0.01822/step. Δ = $0.00357/step (+24% on la).+$0.01822/step. Δ = −$0.00357/step (PinchTab 19.6% cheaper per step).### Reliability@@ -235,18 +232,18 @@ Both lanes passed 72 total verifications except for one step each### How the gap scales with workload-| Scope | Cost/step (pt) | Cost/step (la) | Gap |-|-------|---------------:|---------------:|----:|-| Basic (10 steps, n=5) | $0.01024 | $0.01132 | +10.5% |-| Extended (24 steps, n=3) | $0.01465 | $0.01822 | +24.4% |+| Scope | Cost/step (pt) | Cost/step (la) | PinchTab cheaper |+|-------|---------------:|---------------:|-----------------:|+| Basic (10 steps, n=5) | $0.01024 | $0.01132 | **9.5%** |+| Extended (24 steps, n=3) | $0.01465 | $0.01822 | **19.6%** |Two things move:-1. **The gap widens at longer scope.** On 10 steps agent-browser is ~10%- more expensive per run; on 24 steps it's ~24% more expensive. The- click→snapshot ping-pong pattern compounds — every additional step- that involves a post-action snapshot costs agent-browser an extra- round trip, while PinchTab packs it into one via `--snap-diff`.+1. **The gap widens at longer scope.** PinchTab is ~9.5% cheaper on 10+ steps; on 24 steps it's ~19.6% cheaper. The click→snapshot ping-pong+ pattern compounds — every additional step that involves a post-action+ snapshot costs agent-browser an extra round trip, while PinchTab packs+ it into one via `--snap-diff`.2. **Per-step cost rises for both lanes** as groups 2–5 are added(pt $0.0102 → $0.0147/step, la $0.0113 → $0.0182/step). The latergroups contain structurally harder steps — dashboards with dynamic@@ -255,21 +252,90 @@ Two things move:**agent-browser variance is larger at extended scope.** lae3 (160requests, $0.5132) is a clear outlier; without it la mean drops to-$0.3992 and the gap narrows to ~14%. PinchTab's lpe runs stay in a-tight $0.329–$0.365 band.+$0.3992 and PinchTab's advantage narrows to ~12%. PinchTab's lpe runs+stay in a tight $0.329–$0.365 band.### TakeawayThe extended-scope runs reinforce the basic-scope story but at a larger-magnitude: at production-realistic workloads the PinchTab lane is-meaningfully cheaper (roughly one-quarter less) and uses substantially-fewer API round trips (roughly 45% fewer). The 10% number from the basic-suite understates the gap at scale.+magnitude: at production-realistic workloads PinchTab is meaningfully+cheaper (roughly one-fifth less) and uses substantially fewer API round+trips (roughly 31% fewer). The 9.5% number from the basic suite+understates the gap at scale.For headline citations: use the basic number as the minimum-noiseapples-to-apples anchor (tight groups, high replicate count), and citethe extended number when talking about cost at realistic workload size.+## Sonnet 4.6: Extended Scope (n=2 each, 24 steps)++To check whether the tool-surface gap is **model-invariant** — i.e. does a+stronger model close the gap by using fewer turns on agent-browser's+click→snapshot pattern? — we re-ran the 24-step extended scope with+`claude-sonnet-4-6`, n=2 per lane. Two runs per lane is too few for a+confident headline, but enough to spot whether the ratio between lanes+changes vs Haiku. Logs prefixed `lae-sonnet46-*` (agent-browser) and+`lpe-sonnet46-*` (PinchTab).++### Raw per-run totals++Pricing per 1M tokens (Anthropic Sonnet 4.6): `$3.00` uncached input,+`$3.75` cache-create (1.25×), `$0.30` cache-read (0.1×), `$15.00` output+(5×).++| Run | Requests | Uncached input | Cache create | Cache read | Output | Total tokens | Passed | Pass rate | Cost |+|-----|---------:|---------------:|-------------:|-----------:|-------:|-------------:|-------:|----------:|-----:|+| lpe-sonnet46-1 | 89 | 182,994 | 7,070 | 622,160 | 9,824 | 822,048 | 24 | 100% | $0.9095 |+| lpe-sonnet46-2 | 86 | 174,648 | 7,070 | 600,950 | 9,747 | 792,415 | 24 | 100% | $0.8769 |+| **lpe-sonnet46 avg** | **87.5** | **178,821** | **7,070** | **611,555** | **9,786** | **807,232** | **24.0** | **100%** | **$0.8932** |+| lae-sonnet46-1 | 115 | 213,912 | 6,869 | 783,066 | 12,507 | 1,016,354 | 24 | 100% | $1.0900 |+| lae-sonnet46-2 | 133 | 217,917 | 6,869 | 906,708 | 13,280 | 1,144,774 | 24 | 100% | $1.1507 |+| **lae-sonnet46 avg** | **124.0** | **215,914** | **6,869** | **844,887** | **12,894** | **1,080,564** | **24.0** | **100%** | **$1.1204** |++### Averages (the comparison)++| Lane | Avg requests | Avg uncached input | Avg cache create | Avg cache read | Avg output | Avg total tokens | Avg cost |+|------|-------------:|-------------------:|-----------------:|---------------:|-----------:|-----------------:|---------:|+| PinchTab (lpe-sonnet46-1,2) | **87.5** | 178,821 | 7,070 | 611,555 | 9,786 | **807,232** | **$0.8932** |+| agent-browser (lae-sonnet46-1,2) | **124.0** | 215,914 | 6,869 | 844,887 | 12,894 | **1,080,564** | **$1.1204** |+| Δ (lpe − lae) | −36.5 | −37,093 | +201 | **−233,332** | −3,108 | −273,332 | −$0.2272 |+| PinchTab cheaper (% vs lae) | **29.4%** | 17.2% | −2.9% | **27.6%** | 24.1% | **25.3%** | **20.3%** |++**Per-step** (24 steps per run): PinchTab $0.0372/step, agent-browser+$0.0467/step. Δ = −$0.0095/step (PinchTab 20.3% cheaper per step).++### Model × lane matrix (extended scope)++| Model | Lane | Avg req | Avg total tokens | Avg cost | Cost/step |+|-------|------|--------:|-----------------:|---------:|----------:|+| Haiku 4.5 | PinchTab | 92.3 | 882,244 | $0.3516 | $0.0147 |+| Haiku 4.5 | agent-browser | 134.0 | 1,195,217 | $0.4372 | $0.0182 |+| Sonnet 4.6 | PinchTab | 87.5 | 807,232 | $0.8932 | $0.0372 |+| Sonnet 4.6 | agent-browser | 124.0 | 1,080,564 | $1.1204 | $0.0467 |++### Takeaway++PinchTab's **~20% cost advantage is essentially identical on both+models** at extended scope (Haiku 19.6%, Sonnet 20.3%). Stronger+reasoning doesn't collapse the click→snapshot ping-pong; the extra round+trips are a structural property of the tool surface, not a failure mode+the model fixes with better planning.++Two secondary observations:++- **Sonnet uses slightly fewer requests than Haiku on both lanes** (lpe+ 87.5 vs 92.3, lae 124.0 vs 134.0) — a ~5–7% turn reduction from the+ stronger model. Token totals fall similarly (~9–10%). Not enough to+ matter for the comparison.+- **Sonnet is ~2.5× more expensive per run** than Haiku on the same+ workload (lpe $0.89 vs $0.35; lae $1.12 vs $0.44), which tracks the+ ~3× price ratio discounted slightly by fewer turns.++Two runs is thin — n=2 has very wide confidence intervals and we saw+~7% within-lane spread on lpe and ~6% on lae, so don't read precision+into the 20.3% number. The directional story (the advantage survives a+model change) is the load-bearing result.+## Fairness Caveats### 1. Task-suite bias@@ -334,26 +400,20 @@ and ~13 per agent-browser run vs earlier baselines.## Reproducing This Benchmark```bash-cd tests/benchmark--# 1. Start Docker environment-docker compose up -d --build+# From repo root:-# 2. Initialise reports-./scripts/run-optimization.sh+# 1. Baseline lane (deterministic, ~30 seconds)+./dev opt baseline-# 3. Baseline lane (deterministic, ~30 seconds)-./scripts/baseline.sh+# 2. PinchTab lane (requires Anthropic key)+ANTHROPIC_API_KEY=... ./dev bench pinchtab --groups 0,1-# 4. PinchTab lane (requires Anthropic key)-ANTHROPIC_API_KEY=... ./scripts/run-api-benchmark.ts --lane pinchtab --groups 0,1+# 3. agent-browser lane (requires Anthropic key)+ANTHROPIC_API_KEY=... ./dev bench agent-browser --groups 0,1-# 5. agent-browser lane (requires Anthropic key)-ANTHROPIC_API_KEY=... ./scripts/run-api-benchmark.ts --lane agent-browser --groups 0,1--# 6. Inspect run-level usage-jq '.run_usage' results/pinchtab_benchmark_*.json-jq '.run_usage' results/agent_browser_benchmark_*.json+# 4. Inspect run-level usage+jq '.run_usage' tests/benchmark/results/pinchtab_benchmark_*.json+jq '.run_usage' tests/benchmark/results/agent_browser_benchmark_*.json```## Report Files@@ -369,9 +429,9 @@ Results are written to `tests/benchmark/results/`:## Attached Raw Logs-The transcripts behind the sixteen runs in this document.+The transcripts behind the twenty runs in this document.-### Basic scope (10 steps, groups 0+1, n=5 per lane)+### Basic scope — Haiku 4.5 (10 steps, groups 0+1, n=5 per lane)- [lp1.txt](./logs/lp1.txt) — PinchTab run 1- [lp2.txt](./logs/lp2.txt) — PinchTab run 2@@ -384,7 +444,7 @@ The transcripts behind the sixteen runs in this document.- [la4.txt](./logs/la4.txt) — agent-browser run 4 *(cache-create patched)*- [la5.txt](./logs/la5.txt) — agent-browser run 5-### Extended scope (24 steps, groups 0–5, n=3 per lane)+### Extended scope — Haiku 4.5 (24 steps, groups 0–5, n=3 per lane)- [lpe1.txt](./logs/lpe1.txt) — PinchTab extended run 1- [lpe2.txt](./logs/lpe2.txt) — PinchTab extended run 2@@ -393,6 +453,13 @@ The transcripts behind the sixteen runs in this document.- [lae2.txt](./logs/lae2.txt) — agent-browser extended run 2- [lae3.txt](./logs/lae3.txt) — agent-browser extended run 3+### Extended scope — Sonnet 4.6 (24 steps, groups 0–5, n=2 per lane)++- [lpe-sonnet46-1.txt](./logs/lpe-sonnet46-1.txt) — PinchTab Sonnet 4.6 run 1+- [lpe-sonnet46-2.txt](./logs/lpe-sonnet46-2.txt) — PinchTab Sonnet 4.6 run 2+- [lae1-sonnet46-1.txt](./logs/lae1-sonnet46-1.txt) — agent-browser Sonnet 4.6 run 1+- [lae2-sonnet46-2.txt](./logs/lae2-sonnet46-2.txt) — agent-browser Sonnet 4.6 run 2+Each log contains the full agent conversation, every tool call witharguments, timing, and the `[run-usage]` line at the bottom.Machine-specific paths have been replaced with `<repo>` for portability.@@ -404,7 +471,10 @@ Machine-specific paths have been replaced with `<repo>` for portability.- Basic scope: n=5 per lane; extended scope: n=3 per lane. Run-to-runvariance remains ~25–30% of mean; agent-browser has one outlier ineach scope-- Single model (Haiku 4.5); no Sonnet/Opus comparison+- Two models tested (Haiku 4.5 at n=5 basic / n=3 extended; Sonnet 4.6 at+ n=2 extended). No Opus comparison. Sonnet n=2 is not enough for a tight+ confidence interval on its own number, only for the lane-ratio+ observation- Fixed Docker environment adds per-call overhead roughly equal acrosslanes, but absolute times are not production-representative- Score is pass-count, not answer quality or time-to-completediff --git a/docs/reference/scroll.md b/docs/reference/scroll.mdindex d31c466e..08a377f2 100644--- a/docs/reference/scroll.md+++ b/docs/reference/scroll.md@@ -8,6 +8,8 @@ curl -X POST http://localhost:9867/action \-d '{"kind":"scroll","scrollY":800}'# CLI Alternativepinchtab scroll down+pinchtab scroll down --snap # scroll and output snapshot+pinchtab scroll 800 --snap-diff # scroll and output snapshot diff# Response{"success": true,@@ -19,6 +21,8 @@ pinchtab scroll downNotes:+- use `--snap` to output an interactive snapshot after scrolling+- use `--snap-diff` to output only the changes from the previous snapshot- the top-level CLI also accepts a pixel value such as `pinchtab scroll 800`- the raw API uses `scrollY` and `scrollX` for page scrolling- the raw API can also target an element with `ref` or `selector`diff --git a/internal/bridge/observe/snapshot.go b/internal/bridge/observe/snapshot.goindex 55243678..32c3ea57 100644--- a/internal/bridge/observe/snapshot.go+++ b/internal/bridge/observe/snapshot.go@@ -222,6 +222,25 @@ var InteractiveRoles = map[string]bool{"tab": true, "treeitem": true, "iframe": true, "Iframe": true,}+// ContextRoles are non-actionable but content-bearing roles that give an agent+// structural/semantic context about the page. They are preserved under the+// FilterInteractive filter in addition to InteractiveRoles so `snap -i` returns+// a tree that is usable without a follow-up page-text fetch.+//+// Keep this set tight:+// - Include: headings (structure), tables (cell/columnheader/rowheader), media (image/figure/caption)+// - Exclude: StaticText (duplicates parent names), paragraph/listitem (container noise),+// landmarks (banner/main/navigation/region add no content)+var ContextRoles = map[string]bool{+ "heading": true,+ "image": true,+ "cell": true,+ "columnheader": true,+ "rowheader": true,+ "caption": true,+ "figure": true,+}+const FilterInteractive = "interactive"// isAXNodeHidden checks whether a raw accessibility node has properties@@ -426,7 +445,7 @@ func BuildSnapshot(nodes []RawAXNode, filter string, maxDepth int) ([]A11yNode,return}- if !isSkippableNode(n) && (filter != FilterInteractive || InteractiveRoles[n.Role.String()]) {+ if !isSkippableNode(n) && (filter != FilterInteractive || InteractiveRoles[n.Role.String()] || ContextRoles[n.Role.String()]) {appendNode(n, depth)}diff --git a/internal/bridge/observe/snapshot_format.go b/internal/bridge/observe/snapshot_format.goindex 6c669d62..21f5e71b 100644--- a/internal/bridge/observe/snapshot_format.go+++ b/internal/bridge/observe/snapshot_format.go@@ -65,6 +65,63 @@ func FormatSnapshotCompact(nodes []A11yNode) string {return b.String()}+// FormatSnapshotCompactDiff outputs all current nodes in compact format with+// change markers: [+] for added, [~] for changed. Removed refs are listed at+// the end as [- ref]. This gives agents the full valid ref set plus change info.+func FormatSnapshotCompactDiff(nodes []A11yNode, added, changed, removed []A11yNode) string {+ addedRefs := make(map[string]bool, len(added))+ for _, n := range added {+ addedRefs[n.Ref] = true+ }+ changedRefs := make(map[string]bool, len(changed))+ for _, n := range changed {+ changedRefs[n.Ref] = true+ }++ var b strings.Builder+ for _, n := range nodes {+ b.WriteString(n.Ref)+ b.WriteByte(':')+ b.WriteString(n.Role)+ if n.Name != "" {+ b.WriteString(` "`)+ b.WriteString(n.Name)+ b.WriteByte('"')+ }+ if n.Value != "" {+ b.WriteString(` val="`)+ b.WriteString(n.Value)+ b.WriteByte('"')+ }+ if n.Focused {+ b.WriteString(" *")+ }+ if n.Disabled {+ b.WriteString(" -")+ }+ if n.Hidden {+ b.WriteString(" [hidden]")+ }+ if addedRefs[n.Ref] {+ b.WriteString(" [+]")+ } else if changedRefs[n.Ref] {+ b.WriteString(" [~]")+ }+ b.WriteByte('\n')+ }++ if len(removed) > 0 {+ b.WriteString("# removed:")+ for _, n := range removed {+ b.WriteByte(' ')+ b.WriteString(n.Ref)+ }+ b.WriteByte('\n')+ }++ return b.String()+}+func TruncateToTokens(nodes []A11yNode, maxTokens int, format string) ([]A11yNode, bool) {tokensUsed := 0for i, n := range nodes {diff --git a/internal/bridge/observe_facade.go b/internal/bridge/observe_facade.goindex 1d8cf9ed..871e154d 100644--- a/internal/bridge/observe_facade.go+++ b/internal/bridge/observe_facade.go@@ -11,7 +11,10 @@ const (FilterInteractive = bridgeobserve.FilterInteractive)-var InteractiveRoles = bridgeobserve.InteractiveRoles+var (+ InteractiveRoles = bridgeobserve.InteractiveRoles+ ContextRoles = bridgeobserve.ContextRoles+)type A11yNode = bridgeobserve.A11yNodetype RawAXNode = bridgeobserve.RawAXNode@@ -67,6 +70,10 @@ func FormatSnapshotCompact(nodes []A11yNode) string {return bridgeobserve.FormatSnapshotCompact(nodes)}+func FormatSnapshotCompactDiff(nodes, added, changed, removed []A11yNode) string {+ return bridgeobserve.FormatSnapshotCompactDiff(nodes, added, changed, removed)+}+func TruncateToTokens(nodes []A11yNode, maxTokens int, format string) ([]A11yNode, bool) {return bridgeobserve.TruncateToTokens(nodes, maxTokens, format)}diff --git a/internal/bridge/snapshot_test.go b/internal/bridge/snapshot_test.goindex 3477b480..2a570fac 100644--- a/internal/bridge/snapshot_test.go+++ b/internal/bridge/snapshot_test.go@@ -134,11 +134,106 @@ func TestBuildSnapshotInteractiveFilter(t *testing.T) {flat, _ := BuildSnapshot(nodes, FilterInteractive, -1)- if len(flat) != 1 {- t.Fatalf("expected 1 interactive node, got %d: %+v", len(flat), flat)+ // FilterInteractive keeps InteractiveRoles AND ContextRoles (headings,+ // paragraphs, StaticText, etc.) so agents get structural context without a+ // follow-up page-text fetch. The container WebArea is still filtered out.+ if len(flat) != 2 {+ t.Fatalf("expected 2 nodes (heading + button), got %d: %+v", len(flat), flat)+ }+ if flat[0].Role != "heading" {+ t.Errorf("expected heading first, got %s", flat[0].Role)+ }+ if flat[1].Role != "button" {+ t.Errorf("expected button second, got %s", flat[1].Role)}- if flat[0].Role != "button" {- t.Errorf("expected button, got %s", flat[0].Role)+}++func TestBuildSnapshotInteractiveExcludesLandmarks(t *testing.T) {+ // The relaxed interactive filter must NOT include landmark-only roles+ // (banner, main, navigation, region) which bloat output without adding+ // content — the agent infers structure from heading nesting instead.+ nodes := []RawAXNode{+ {+ NodeID: "root",+ Role: &RawAXValue{Value: json.RawMessage(`"WebArea"`)},+ Name: &RawAXValue{Value: json.RawMessage(`"Page"`)},+ ChildIDs: []string{"nav", "main", "btn"},+ BackendDOMNodeID: 1,+ },+ {+ NodeID: "nav",+ Role: &RawAXValue{Value: json.RawMessage(`"navigation"`)},+ Name: &RawAXValue{Value: json.RawMessage(`"Primary"`)},+ BackendDOMNodeID: 10,+ },+ {+ NodeID: "main",+ Role: &RawAXValue{Value: json.RawMessage(`"main"`)},+ Name: &RawAXValue{Value: json.RawMessage(`"Content"`)},+ BackendDOMNodeID: 11,+ },+ {+ NodeID: "btn",+ Role: &RawAXValue{Value: json.RawMessage(`"button"`)},+ Name: &RawAXValue{Value: json.RawMessage(`"Go"`)},+ BackendDOMNodeID: 12,+ },+ }++ flat, _ := BuildSnapshot(nodes, FilterInteractive, -1)++ for _, n := range flat {+ if n.Role == "navigation" || n.Role == "main" || n.Role == "banner" || n.Role == "region" {+ t.Errorf("landmark role %q leaked into interactive snapshot: %+v", n.Role, n)+ }+ }+ // Only the button should pass the filter here.+ if len(flat) != 1 || flat[0].Role != "button" {+ t.Fatalf("expected exactly [button], got %+v", flat)+ }+}++func TestBuildSnapshotInteractiveIncludesContext(t *testing.T) {+ // Directly assert each ContextRole we care about is preserved by+ // FilterInteractive. If someone adds/removes a role to ContextRoles+ // without updating this test, they'll catch it immediately.+ roleNames := []string{"heading", "image", "cell", "columnheader", "rowheader"}+ nodes := []RawAXNode{+ {+ NodeID: "root",+ Role: &RawAXValue{Value: json.RawMessage(`"WebArea"`)},+ Name: &RawAXValue{Value: json.RawMessage(`"Page"`)},+ ChildIDs: []string{"h", "i", "c", "ch", "rh"},+ BackendDOMNodeID: 1,+ },+ {NodeID: "h", Role: &RawAXValue{Value: json.RawMessage(`"heading"`)}, Name: &RawAXValue{Value: json.RawMessage(`"H"`)}, BackendDOMNodeID: 10},+ {NodeID: "i", Role: &RawAXValue{Value: json.RawMessage(`"image"`)}, Name: &RawAXValue{Value: json.RawMessage(`"Img"`)}, BackendDOMNodeID: 11},+ {NodeID: "c", Role: &RawAXValue{Value: json.RawMessage(`"cell"`)}, Name: &RawAXValue{Value: json.RawMessage(`"Cell"`)}, BackendDOMNodeID: 12},+ {NodeID: "ch", Role: &RawAXValue{Value: json.RawMessage(`"columnheader"`)}, Name: &RawAXValue{Value: json.RawMessage(`"Col"`)}, BackendDOMNodeID: 13},+ {NodeID: "rh", Role: &RawAXValue{Value: json.RawMessage(`"rowheader"`)}, Name: &RawAXValue{Value: json.RawMessage(`"Row"`)}, BackendDOMNodeID: 14},+ }++ flat, _ := BuildSnapshot(nodes, FilterInteractive, -1)++ gotRoles := make(map[string]bool, len(flat))+ for _, n := range flat {+ gotRoles[n.Role] = true+ }+ for _, want := range roleNames {+ if !gotRoles[want] {+ t.Errorf("context role %q dropped by interactive filter; got roles %v", want, gotRoles)+ }+ }+}++func TestContextRolesDoesNotOverlapInteractiveRoles(t *testing.T) {+ // Guardrail: ContextRoles is a parallel set for structural context.+ // If a role shifts into InteractiveRoles, the dual registration will+ // silently duplicate behavior and make future audits harder — surface it.+ for r := range ContextRoles {+ if InteractiveRoles[r] {+ t.Errorf("role %q is registered in both ContextRoles and InteractiveRoles", r)+ }}}diff --git a/internal/cli/actions/actions_cache.go b/internal/cli/actions/actions_cache.goindex 53174379..fce8cdbe 100644--- a/internal/cli/actions/actions_cache.go+++ b/internal/cli/actions/actions_cache.go@@ -12,11 +12,18 @@ import (// CacheClear clears the browser's HTTP disk cache.func CacheClear(client *http.Client, base, token string, cmd *cobra.Command) {- // DoPost already prints the JSON response- result := apiclient.DoPost(client, base, token, "/cache/clear", nil)+ result := apiclient.DoPostQuiet(client, base, token, "/cache/clear", nil)if result == nil {- fmt.Fprintln(os.Stderr, "Failed to clear cache")- os.Exit(1)+ fmt.Fprintln(os.Stderr, "ERROR: cache: clear failed")+ os.Exit(2)+ }++ jsonOut, _ := cmd.Flags().GetBool("json")+ if jsonOut {+ out, _ := json.MarshalIndent(result, "", " ")+ fmt.Println(string(out))+ } else {+ fmt.Println("OK")}}@@ -24,16 +31,25 @@ func CacheClear(client *http.Client, base, token string, cmd *cobra.Command) {func CacheStatus(client *http.Client, base, token string, cmd *cobra.Command) {result := apiclient.DoGetRaw(client, base, token, "/cache/status", nil)if result == nil {- fmt.Fprintln(os.Stderr, "Failed to get cache status")- os.Exit(1)+ fmt.Fprintln(os.Stderr, "ERROR: cache: status check failed")+ os.Exit(2)}var buf map[string]anyif err := json.Unmarshal(result, &buf); err != nil {- fmt.Fprintf(os.Stderr, "Failed to parse response: %v\n", err)- os.Exit(1)+ fmt.Fprintf(os.Stderr, "ERROR: cache: %v\n", err)+ os.Exit(2)}- out, _ := json.MarshalIndent(buf, "", " ")- fmt.Println(string(out))+ jsonOut, _ := cmd.Flags().GetBool("json")+ if jsonOut {+ out, _ := json.MarshalIndent(buf, "", " ")+ fmt.Println(string(out))+ } else {+ if canClear, ok := buf["canClear"].(bool); ok && canClear {+ fmt.Println("can-clear")+ } else {+ fmt.Println("cache-empty")+ }+ }}diff --git a/internal/cli/actions/actions_dialog.go b/internal/cli/actions/actions_dialog.goindex aaec7364..36aaf09c 100644--- a/internal/cli/actions/actions_dialog.go+++ b/internal/cli/actions/actions_dialog.go@@ -1,21 +1,31 @@package actionsimport (- "fmt""net/http""github.com/pinchtab/pinchtab/internal/cli/apiclient"+ "github.com/pinchtab/pinchtab/internal/cli/output"+ "github.com/spf13/cobra")// Dialog handles a JavaScript dialog (accept or dismiss).-func Dialog(client *http.Client, base, token string, action string, text string, tabID string) {+func Dialog(client *http.Client, base, token string, action string, text string, cmd *cobra.Command) {body := map[string]any{"action": action}if text != "" {body["text"] = text}+ tabID, _ := cmd.Flags().GetString("tab")path := "/dialog"if tabID != "" {- path = fmt.Sprintf("/tabs/%s/dialog", tabID)+ path = "/tabs/" + tabID + "/dialog"}- apiclient.DoPost(client, base, token, path, body)++ jsonOutput, _ := cmd.Flags().GetBool("json")+ if jsonOutput {+ apiclient.DoPost(client, base, token, path, body)+ return+ }++ apiclient.DoPostQuiet(client, base, token, path, body)+ output.Success()}diff --git a/internal/cli/actions/actions_element.go b/internal/cli/actions/actions_element.goindex 69b71c47..c8ebc266 100644--- a/internal/cli/actions/actions_element.go+++ b/internal/cli/actions/actions_element.go@@ -1,7 +1,7 @@package actionsimport (- "fmt"+ "encoding/json""net/http""strconv""strings"@@ -9,6 +9,7 @@ import ("github.com/pinchtab/pinchtab/internal/bridge""github.com/pinchtab/pinchtab/internal/cli""github.com/pinchtab/pinchtab/internal/cli/apiclient"+ "github.com/pinchtab/pinchtab/internal/cli/output""github.com/pinchtab/pinchtab/internal/selector""github.com/spf13/cobra")@@ -90,9 +91,82 @@ func postActionWithHeaders(client *http.Client, base, token string, cmd *cobra.CtabID, _ := cmd.Flags().GetString("tab")path := "/action"if tabID != "" {- path = fmt.Sprintf("/tabs/%s/action", tabID)+ path = "/tabs/" + tabID + "/action"}- apiclient.DoPostWithHeaders(client, base, token, path, body, headers)++ // Default to terse output; --json flag enables full JSON response+ jsonOutput, _ := cmd.Flags().GetBool("json")+ if jsonOutput {+ apiclient.DoPostWithHeaders(client, base, token, path, body, headers)+ return+ }++ // Quiet mode: print simple success message+ result := apiclient.DoPostQuietWithHeaders(client, base, token, path, body, headers)+ kind, _ := body["kind"].(string)+ printActionResult(kind, result)++ // If --snap or --snap-diff flag is set, fetch and output snapshot+ snap, _ := cmd.Flags().GetBool("snap")+ snapDiff, _ := cmd.Flags().GetBool("snap-diff")+ if snap || snapDiff {+ fetchAndPrintSnapshot(client, base, token, tabID, snapDiff)+ }++ // If --text flag is set, fetch and output text content+ text, _ := cmd.Flags().GetBool("text")+ if text {+ fetchAndPrintText(client, base, token, tabID)+ }+}++func fetchAndPrintSnapshot(client *http.Client, base, token, tabID string, diff bool) {+ params := "filter=interactive&format=compact"+ if diff {+ params += "&diff=true"+ }+ if tabID != "" {+ params += "&tabId=" + tabID+ }+ apiclient.DoGetRawAndPrint(client, base, token, "/snapshot?"+params)+}++func fetchAndPrintText(client *http.Client, base, token, tabID string) {+ path := "/text"+ if tabID != "" {+ path = "/tabs/" + tabID + "/text"+ }+ body := apiclient.DoGetRaw(client, base, token, path, nil)+ var result struct {+ Text string `json:"text"`+ }+ if err := json.Unmarshal(body, &result); err != nil {+ output.Value(string(body))+ return+ }+ output.Value(result.Text)+}++func printActionResult(kind string, result map[string]any) {+ // Check for failure+ if success, ok := result["success"].(bool); ok && !success {+ errMsg := "unknown error"+ if msg, ok := result["error"].(string); ok {+ errMsg = msg+ }+ // Check for recovery hints+ if recovery, ok := result["recovery"].(map[string]any); ok {+ if failType, ok := recovery["failure_type"].(string); ok {+ if failType == "stale" || failType == "navigation" {+ output.Hint("ref may be stale — run `pinchtab snap -i` to refresh")+ }+ }+ }+ output.Error(kind, errMsg, output.ExitNotFound)+ return+ }++ output.Success()}func setPointBody(body map[string]any, x, y float64) {diff --git a/internal/cli/actions/actions_evaluate.go b/internal/cli/actions/actions_evaluate.goindex 16539fce..4269f38d 100644--- a/internal/cli/actions/actions_evaluate.go+++ b/internal/cli/actions/actions_evaluate.go@@ -1,11 +1,13 @@package actionsimport (+ "encoding/json""fmt"- "github.com/pinchtab/pinchtab/internal/cli/apiclient"- "github.com/spf13/cobra""net/http""strings"++ "github.com/pinchtab/pinchtab/internal/cli/apiclient"+ "github.com/spf13/cobra")func Evaluate(client *http.Client, base, token string, args []string, cmd *cobra.Command) {@@ -16,7 +18,32 @@ func Evaluate(client *http.Client, base, token string, args []string, cmd *cobratabID, _ := cmd.Flags().GetString("tab")path := "/evaluate"if tabID != "" {- path = fmt.Sprintf("/tabs/%s/evaluate", tabID)+ path = "/tabs/" + tabID + "/evaluate"+ }++ jsonOutput, _ := cmd.Flags().GetBool("json")+ if jsonOutput {+ apiclient.DoPost(client, base, token, path, body)+ return+ }++ // Terse: scalar verbatim, object/array as compact JSON+ result := apiclient.DoPostQuiet(client, base, token, path, body)+ if val, ok := result["result"]; ok {+ switch v := val.(type) {+ case string:+ fmt.Println(v)+ case float64, bool:+ fmt.Println(v)+ case nil:+ fmt.Println("null")+ default:+ // Object or array: compact JSON+ if data, err := json.Marshal(v); err == nil {+ fmt.Println(string(data))+ } else {+ fmt.Println(v)+ }+ }}- apiclient.DoPost(client, base, token, path, body)}diff --git a/internal/cli/actions/actions_find.go b/internal/cli/actions/actions_find.goindex 397a372a..1c097139 100644--- a/internal/cli/actions/actions_find.go+++ b/internal/cli/actions/actions_find.go@@ -6,6 +6,7 @@ import ("github.com/pinchtab/pinchtab/internal/cli""github.com/pinchtab/pinchtab/internal/cli/apiclient"+ "github.com/pinchtab/pinchtab/internal/cli/output""github.com/spf13/cobra")@@ -14,6 +15,7 @@ func Find(client *http.Client, base, token string, query string, cmd *cobra.Commthreshold, _ := cmd.Flags().GetString("threshold")explain, _ := cmd.Flags().GetBool("explain")refOnly, _ := cmd.Flags().GetBool("ref-only")+ jsonOutput, _ := cmd.Flags().GetBool("json")body := map[string]any{"query": query}if threshold != "" {@@ -25,16 +27,43 @@ func Find(client *http.Client, base, token string, query string, cmd *cobra.Commpath := "/find"if tabID != "" {- path = fmt.Sprintf("/tabs/%s/find", tabID)+ path = "/tabs/" + tabID + "/find"}- result := apiclient.DoPost(client, base, token, path, body)-+ // --ref-only: just print the best refif refOnly {+ result := apiclient.DoPostQuiet(client, base, token, path, body)if ref, ok := result["best_ref"].(string); ok && ref != "" {fmt.Println(ref)return}cli.Fatal("No element found")}++ // --json: full JSON output+ if jsonOutput {+ apiclient.DoPost(client, base, token, path, body)+ return+ }++ // Terse: one line per match: <ref>\t<role>\t"<name>"+ result := apiclient.DoPostQuiet(client, base, token, path, body)+ matches, ok := result["matches"].([]any)+ if !ok || len(matches) == 0 {+ // Single result format+ if ref, ok := result["best_ref"].(string); ok && ref != "" {+ role, _ := result["role"].(string)+ name, _ := result["name"].(string)+ output.Value(fmt.Sprintf("%s\t%s\t%q", ref, role, name))+ }+ return+ }+ for _, m := range matches {+ if match, ok := m.(map[string]any); ok {+ ref, _ := match["ref"].(string)+ role, _ := match["role"].(string)+ name, _ := match["name"].(string)+ fmt.Printf("%s\t%s\t%q\n", ref, role, name)+ }+ }}diff --git a/internal/cli/actions/actions_navigate.go b/internal/cli/actions/actions_navigate.goindex 86dcaa92..2726e6e3 100644--- a/internal/cli/actions/actions_navigate.go+++ b/internal/cli/actions/actions_navigate.go@@ -2,31 +2,43 @@ package actionsimport ("fmt"+ "net/http"+"github.com/pinchtab/pinchtab/internal/cli/apiclient"+ "github.com/pinchtab/pinchtab/internal/cli/output""github.com/spf13/cobra"- "net/http"- "os")-// stdoutIsPipe reports whether stdout is a pipe/redirect rather than a-// terminal. Used to switch `nav` into machine-friendly output mode so-// `export PINCHTAB_TAB=$(pinchtab nav URL)` captures just the tab ID.-func stdoutIsPipe() bool {- fi, err := os.Stdout.Stat()- if err != nil {- return false- }- return (fi.Mode() & os.ModeCharDevice) == 0-}-// Back navigates the current (or specified) tab back in history.func Back(client *http.Client, base, token string, cmd *cobra.Command) {tabID, _ := cmd.Flags().GetString("tab")path := "/back"if tabID != "" {- path = fmt.Sprintf("/tabs/%s/back", tabID)+ path = "/tabs/" + tabID + "/back"+ }++ jsonOutput, _ := cmd.Flags().GetBool("json")+ if jsonOutput {+ apiclient.DoPost(client, base, token, path, nil)+ return+ }++ result := apiclient.DoPostQuiet(client, base, token, path, nil)+ if url, ok := result["url"].(string); ok {+ output.Value(url)+ } else {+ output.Success()+ }++ snap, _ := cmd.Flags().GetBool("snap")+ snapDiff, _ := cmd.Flags().GetBool("snap-diff")+ if snap || snapDiff {+ fetchAndPrintSnapshot(client, base, token, tabID, snapDiff)+ }+ text, _ := cmd.Flags().GetBool("text")+ if text {+ fetchAndPrintText(client, base, token, tabID)}- apiclient.DoPost(client, base, token, path, nil)}// Forward navigates the current (or specified) tab forward in history.@@ -34,9 +46,31 @@ func Forward(client *http.Client, base, token string, cmd *cobra.Command) {tabID, _ := cmd.Flags().GetString("tab")path := "/forward"if tabID != "" {- path = fmt.Sprintf("/tabs/%s/forward", tabID)+ path = "/tabs/" + tabID + "/forward"+ }++ jsonOutput, _ := cmd.Flags().GetBool("json")+ if jsonOutput {+ apiclient.DoPost(client, base, token, path, nil)+ return+ }++ result := apiclient.DoPostQuiet(client, base, token, path, nil)+ if url, ok := result["url"].(string); ok {+ output.Value(url)+ } else {+ output.Success()+ }++ snap, _ := cmd.Flags().GetBool("snap")+ snapDiff, _ := cmd.Flags().GetBool("snap-diff")+ if snap || snapDiff {+ fetchAndPrintSnapshot(client, base, token, tabID, snapDiff)+ }+ text, _ := cmd.Flags().GetBool("text")+ if text {+ fetchAndPrintText(client, base, token, tabID)}- apiclient.DoPost(client, base, token, path, nil)}// Reload reloads the current (or specified) tab.@@ -44,14 +78,33 @@ func Reload(client *http.Client, base, token string, cmd *cobra.Command) {tabID, _ := cmd.Flags().GetString("tab")path := "/reload"if tabID != "" {- path = fmt.Sprintf("/tabs/%s/reload", tabID)+ path = "/tabs/" + tabID + "/reload"+ }++ jsonOutput, _ := cmd.Flags().GetBool("json")+ if jsonOutput {+ apiclient.DoPost(client, base, token, path, nil)+ return+ }++ apiclient.DoPostQuiet(client, base, token, path, nil)+ output.Success()++ snap, _ := cmd.Flags().GetBool("snap")+ snapDiff, _ := cmd.Flags().GetBool("snap-diff")+ if snap || snapDiff {+ fetchAndPrintSnapshot(client, base, token, tabID, snapDiff)+ }+ text, _ := cmd.Flags().GetBool("text")+ if text {+ fetchAndPrintText(client, base, token, tabID)}- apiclient.DoPost(client, base, token, path, nil)}-func Navigate(client *http.Client, base, token string, url string, cmd *cobra.Command) {+func Navigate(client *http.Client, base, token string, url string, cmd *cobra.Command) string {body := map[string]any{"url": url}- if v, _ := cmd.Flags().GetBool("new-tab"); v {+ newTab, _ := cmd.Flags().GetBool("new-tab")+ if newTab {body["newTab"] = true}if v, _ := cmd.Flags().GetBool("block-images"); v {@@ -62,22 +115,33 @@ func Navigate(client *http.Client, base, token string, url string, cmd *cobra.Co}tabID, _ := cmd.Flags().GetString("tab")path := "/navigate"- if tabID != "" {- path = fmt.Sprintf("/tabs/%s/navigate", tabID)- }-- // Machine-friendly output: emit only the tabId when --print-tab-id is set- // or when stdout is a pipe/redirect. Enables:- // export PINCHTAB_TAB=$(pinchtab nav http://example.com)- printTabID, _ := cmd.Flags().GetBool("print-tab-id")- if printTabID || stdoutIsPipe() {- result := apiclient.DoPostQuiet(client, base, token, path, body)- if tid, ok := result["tabId"].(string); ok && tid != "" {- fmt.Println(tid)- }- return+ // Don't use tab-specific path when creating a new tab+ if tabID != "" && !newTab {+ path = "/tabs/" + tabID + "/navigate"+ }++ // JSON output mode+ jsonOutput, _ := cmd.Flags().GetBool("json")+ if jsonOutput {+ result := apiclient.DoPost(client, base, token, path, body)+ apiclient.SuggestNextAction("navigate", result)+ return ""+ }++ // Terse mode: emit only the tabId (default, or when --print-tab-id / pipe)+ result := apiclient.DoPostQuiet(client, base, token, path, body)+ resultTabID := ""+ if tid, ok := result["tabId"].(string); ok && tid != "" {+ resultTabID = tid+ fmt.Println(tid)+ }++ // If --snap or --snap-diff flag is set, fetch and output snapshot+ snap, _ := cmd.Flags().GetBool("snap")+ snapDiff, _ := cmd.Flags().GetBool("snap-diff")+ if snap || snapDiff {+ fetchAndPrintSnapshot(client, base, token, resultTabID, snapDiff)}- result := apiclient.DoPost(client, base, token, path, body)- apiclient.SuggestNextAction("navigate", result)+ return resultTabID}diff --git a/internal/cli/actions/actions_snapshot.go b/internal/cli/actions/actions_snapshot.goindex 3f2e38a1..20c5a67d 100644--- a/internal/cli/actions/actions_snapshot.go+++ b/internal/cli/actions/actions_snapshot.go@@ -9,11 +9,14 @@ import (func Snapshot(client *http.Client, base, token string, cmd *cobra.Command) {params := url.Values{}- if v, _ := cmd.Flags().GetBool("interactive"); v {- params.Set("filter", "interactive")- }- if v, _ := cmd.Flags().GetBool("compact"); v {- params.Set("format", "compact")+ full, _ := cmd.Flags().GetBool("full")+ if !full {+ if v, _ := cmd.Flags().GetBool("interactive"); v {+ params.Set("filter", "interactive")+ }+ if v, _ := cmd.Flags().GetBool("compact"); v {+ params.Set("format", "compact")+ }}if v, _ := cmd.Flags().GetBool("text"); v {params.Set("format", "text")diff --git a/internal/cli/actions/actions_system.go b/internal/cli/actions/actions_system.goindex c08e4357..be65fa09 100644--- a/internal/cli/actions/actions_system.go+++ b/internal/cli/actions/actions_system.go@@ -3,16 +3,42 @@ package actionsimport ("encoding/json""fmt"- "github.com/pinchtab/pinchtab/internal/cli"- "github.com/pinchtab/pinchtab/internal/cli/apiclient""io""log""net/http""os"++ "github.com/pinchtab/pinchtab/internal/cli"+ "github.com/pinchtab/pinchtab/internal/cli/apiclient"+ "github.com/pinchtab/pinchtab/internal/cli/output"+ "github.com/spf13/cobra")-func Health(client *http.Client, base, token string) {- apiclient.DoGet(client, base, token, "/health", nil)+func Health(client *http.Client, base, token string, cmd *cobra.Command) {+ jsonOutput, _ := cmd.Flags().GetBool("json")+ if jsonOutput {+ apiclient.DoGet(client, base, token, "/health", nil)+ return+ }++ // Terse: "ok" or "degraded: <reason>"+ body := apiclient.DoGetRaw(client, base, token, "/health", nil)+ var result map[string]any+ if err := json.Unmarshal(body, &result); err != nil {+ output.Value("ok")+ return+ }+ status, _ := result["status"].(string)+ if status == "ok" {+ output.Value("ok")+ } else {+ reason, _ := result["reason"].(string)+ if reason != "" {+ output.Value("degraded: " + reason)+ } else {+ output.Value(status)+ }+ }}func Instances(client *http.Client, base, token string) {diff --git a/internal/cli/actions/actions_system_test.go b/internal/cli/actions/actions_system_test.goindex 874908dc..9bd3854f 100644--- a/internal/cli/actions/actions_system_test.go+++ b/internal/cli/actions/actions_system_test.go@@ -2,15 +2,24 @@ package actionsimport ("testing"++ "github.com/spf13/cobra")+func newHealthCmd() *cobra.Command {+ cmd := &cobra.Command{}+ cmd.Flags().Bool("json", false, "")+ return cmd+}+func TestHealth(t *testing.T) {m := newMockServer()m.response = `{"status":"ok","version":"dev"}`defer m.close()client := m.server.Client()- Health(client, m.base(), "")+ cmd := newHealthCmd()+ Health(client, m.base(), "", cmd)if m.lastPath != "/health" {t.Errorf("expected /health, got %s", m.lastPath)}@@ -21,7 +30,8 @@ func TestAuthHeader(t *testing.T) {defer m.close()client := m.server.Client()- Health(client, m.base(), "my-secret-token")+ cmd := newHealthCmd()+ Health(client, m.base(), "my-secret-token", cmd)auth := m.lastHeaders.Get("Authorization")if auth != "Bearer my-secret-token" {t.Errorf("expected 'Bearer my-secret-token', got %q", auth)@@ -33,7 +43,8 @@ func TestNoAuthHeader(t *testing.T) {defer m.close()client := m.server.Client()- Health(client, m.base(), "")+ cmd := newHealthCmd()+ Health(client, m.base(), "", cmd)auth := m.lastHeaders.Get("Authorization")if auth != "" {t.Errorf("expected no auth header, got %q", auth)diff --git a/internal/cli/actions/actions_tabs.go b/internal/cli/actions/actions_tabs.goindex 1aa8b062..0c37b417 100644--- a/internal/cli/actions/actions_tabs.go+++ b/internal/cli/actions/actions_tabs.go@@ -1,21 +1,47 @@package actionsimport (+ "encoding/json""fmt""net/http""os""github.com/pinchtab/pinchtab/internal/cli""github.com/pinchtab/pinchtab/internal/cli/apiclient"+ "github.com/pinchtab/pinchtab/internal/cli/output"+ "github.com/spf13/cobra")// TabList lists all open tabs.-func TabList(client *http.Client, base, token string) {- apiclient.DoGet(client, base, token, "/tabs", nil)+func TabList(client *http.Client, base, token string, cmd *cobra.Command) {+ jsonOutput, _ := cmd.Flags().GetBool("json")+ if jsonOutput {+ apiclient.DoGet(client, base, token, "/tabs", nil)+ return+ }++ // Terse: one line per tab: [*]<id>\t<url>\t<title>+ body := apiclient.DoGetRaw(client, base, token, "/tabs", nil)+ var tabs []map[string]any+ if err := json.Unmarshal(body, &tabs); err != nil {+ fmt.Println(string(body))+ return+ }+ for _, tab := range tabs {+ id, _ := tab["id"].(string)+ url, _ := tab["url"].(string)+ title, _ := tab["title"].(string)+ active, _ := tab["active"].(bool)+ prefix := ""+ if active {+ prefix = "*"+ }+ fmt.Printf("%s%s\t%s\t%s\n", prefix, id, url, title)+ }}// TabNew opens a new tab (exported for cobra subcommand).-func TabNew(client *http.Client, base, token string, body map[string]any) {+func TabNew(client *http.Client, base, token string, body map[string]any, cmd *cobra.Command) {// Check if any instances are runninginstances := getInstances(client, base, token)if len(instances) == 0 {@@ -23,22 +49,54 @@ func TabNew(client *http.Client, base, token string, body map[string]any) {launchInstance(client, base, token, "default")fmt.Fprintln(os.Stderr, cli.StyleStderr(cli.SuccessStyle, "Instance launched"))}- apiclient.DoPost(client, base, token, "/tab", body)++ jsonOutput, _ := cmd.Flags().GetBool("json")+ if jsonOutput {+ apiclient.DoPost(client, base, token, "/tab", body)+ return+ }++ result := apiclient.DoPostQuiet(client, base, token, "/tab", body)+ if tabID, ok := result["tabId"].(string); ok {+ output.Value(tabID)+ } else {+ output.Success()+ }}// TabClose closes a tab by ID.-func TabClose(client *http.Client, base, token string, tabID string) {- apiclient.DoPost(client, base, token, "/tab", map[string]any{+func TabClose(client *http.Client, base, token string, tabID string, cmd *cobra.Command) {+ jsonOutput, _ := cmd.Flags().GetBool("json")+ if jsonOutput {+ apiclient.DoPost(client, base, token, "/tab", map[string]any{+ "action": "close",+ "tabId": tabID,+ })+ return+ }++ apiclient.DoPostQuiet(client, base, token, "/tab", map[string]any{"action": "close","tabId": tabID,})+ output.Success()}// TabFocus switches to a tab by ID, making it the active tab// for subsequent commands.-func TabFocus(client *http.Client, base, token string, tabID string) {- apiclient.DoPost(client, base, token, "/tab", map[string]any{+func TabFocus(client *http.Client, base, token string, tabID string, cmd *cobra.Command) {+ jsonOutput, _ := cmd.Flags().GetBool("json")+ if jsonOutput {+ apiclient.DoPost(client, base, token, "/tab", map[string]any{+ "action": "focus",+ "tabId": tabID,+ })+ return+ }++ apiclient.DoPostQuiet(client, base, token, "/tab", map[string]any{"action": "focus","tabId": tabID,})+ output.Value(tabID)}diff --git a/internal/cli/actions/actions_text.go b/internal/cli/actions/actions_text.goindex d2f51dac..8369a722 100644--- a/internal/cli/actions/actions_text.go+++ b/internal/cli/actions/actions_text.go@@ -1,10 +1,12 @@package actionsimport (+ "encoding/json""net/http""net/url""github.com/pinchtab/pinchtab/internal/cli/apiclient"+ "github.com/pinchtab/pinchtab/internal/cli/output""github.com/pinchtab/pinchtab/internal/selector""github.com/spf13/cobra")@@ -48,5 +50,22 @@ func Text(client *http.Client, base, token string, cmd *cobra.Command, args []st}}- apiclient.DoGet(client, base, token, "/text", params)+ // Default to terse output (just text); --json for full response+ jsonOutput, _ := cmd.Flags().GetBool("json")+ if jsonOutput {+ apiclient.DoGet(client, base, token, "/text", params)+ return+ }++ // Terse mode: print just the text content+ body := apiclient.DoGetRaw(client, base, token, "/text", params)+ var result struct {+ Text string `json:"text"`+ }+ if err := json.Unmarshal(body, &result); err != nil {+ // Not JSON, print raw+ output.Value(string(body))+ return+ }+ output.Value(result.Text)}diff --git a/internal/cli/actions/actions_text_test.go b/internal/cli/actions/actions_text_test.goindex 5f34083a..cba9d7e0 100644--- a/internal/cli/actions/actions_text_test.go+++ b/internal/cli/actions/actions_text_test.go@@ -13,6 +13,8 @@ func newTextCmd() *cobra.Command {cmd.Flags().Bool("full", false, "")cmd.Flags().String("tab", "", "")cmd.Flags().String("frame", "", "")+ cmd.Flags().String("selector", "", "")+ cmd.Flags().Bool("json", false, "")return cmd}@@ -23,7 +25,7 @@ func TestText(t *testing.T) {client := m.server.Client()cmd := newTextCmd()- Text(client, m.base(), "", cmd)+ Text(client, m.base(), "", cmd, nil)if m.lastPath != "/text" {t.Errorf("expected /text, got %s", m.lastPath)}@@ -36,7 +38,7 @@ func TestTextRaw(t *testing.T) {cmd := newTextCmd()_ = cmd.Flags().Set("raw", "true")- Text(client, m.base(), "", cmd)+ Text(client, m.base(), "", cmd, nil)if !strings.Contains(m.lastQuery, "mode=raw") {t.Errorf("expected mode=raw, got %s", m.lastQuery)}@@ -52,7 +54,7 @@ func TestTextFull(t *testing.T) {cmd := newTextCmd()_ = cmd.Flags().Set("full", "true")- Text(client, m.base(), "", cmd)+ Text(client, m.base(), "", cmd, nil)if !strings.Contains(m.lastQuery, "mode=raw") {t.Errorf("expected --full to set mode=raw, got %s", m.lastQuery)}@@ -68,7 +70,7 @@ func TestTextFrame(t *testing.T) {cmd := newTextCmd()_ = cmd.Flags().Set("frame", "FRAME123")- Text(client, m.base(), "", cmd)+ Text(client, m.base(), "", cmd, nil)if !strings.Contains(m.lastQuery, "frameId=FRAME123") {t.Errorf("expected frameId=FRAME123, got %s", m.lastQuery)}@@ -81,7 +83,7 @@ func TestTextTab(t *testing.T) {cmd := newTextCmd()_ = cmd.Flags().Set("tab", "TAB1")- Text(client, m.base(), "", cmd)+ Text(client, m.base(), "", cmd, nil)if !strings.Contains(m.lastQuery, "tabId=TAB1") {t.Errorf("expected tabId=TAB1, got %s", m.lastQuery)}diff --git a/internal/cli/actions/actions_wait.go b/internal/cli/actions/actions_wait.goindex f2ec6a27..25641d8a 100644--- a/internal/cli/actions/actions_wait.go+++ b/internal/cli/actions/actions_wait.go@@ -6,6 +6,7 @@ import ("strconv""github.com/pinchtab/pinchtab/internal/cli/apiclient"+ "github.com/pinchtab/pinchtab/internal/cli/output""github.com/spf13/cobra")@@ -54,8 +55,20 @@ func Wait(client *http.Client, base, token string, args []string, cmd *cobra.Compath := "/wait"if tabID != "" {- path = fmt.Sprintf("/tabs/%s/wait", tabID)+ path = "/tabs/" + tabID + "/wait"}- apiclient.DoPost(client, base, token, path, body)+ jsonOutput, _ := cmd.Flags().GetBool("json")+ if jsonOutput {+ apiclient.DoPost(client, base, token, path, body)+ return+ }++ result := apiclient.DoPostQuiet(client, base, token, path, body)+ // Server returns waited=false when condition isn't met within timeout+ if waited, ok := result["waited"].(bool); ok && !waited {+ output.Error("wait", "timeout", output.ExitTimeout)+ return+ }+ output.Success()}diff --git a/internal/cli/apiclient/client.go b/internal/cli/apiclient/client.goindex b821b273..69584e44 100644--- a/internal/cli/apiclient/client.go+++ b/internal/cli/apiclient/client.go@@ -56,6 +56,24 @@ func DoGetRaw(client *http.Client, base, token, path string, params url.Values)return body}+// DoGetRawAndPrint fetches and prints the raw response body (for --snap flag).+func DoGetRawAndPrint(client *http.Client, base, token, pathWithQuery string) {+ req, _ := http.NewRequest("GET", base+pathWithQuery, nil)+ setClientHeaders(req, token)+ resp, err := client.Do(req)+ if err != nil {+ fmt.Fprintf(os.Stderr, "snapshot failed: %v\n", err)+ return+ }+ defer func() { _ = resp.Body.Close() }()+ body, _ := io.ReadAll(resp.Body)+ if resp.StatusCode >= 400 {+ fmt.Fprintf(os.Stderr, "snapshot error %d: %s\n", resp.StatusCode, string(body))+ return+ }+ fmt.Println(string(body))+}+func DoPost(client *http.Client, base, token, path string, body map[string]any) map[string]any {return DoPostWithHeaders(client, base, token, path, body, nil)}@@ -64,10 +82,18 @@ func DoPost(client *http.Client, base, token, path string, body map[string]any)// responsible for rendering whatever output is appropriate (e.g. a single// field for machine-friendly piping).func DoPostQuiet(client *http.Client, base, token, path string, body map[string]any) map[string]any {+ return DoPostQuietWithHeaders(client, base, token, path, body, nil)+}++// DoPostQuietWithHeaders is like DoPostQuiet but allows custom headers.+func DoPostQuietWithHeaders(client *http.Client, base, token, path string, body map[string]any, headers map[string]string) map[string]any {data, _ := json.Marshal(body)req, _ := http.NewRequest("POST", base+path, bytes.NewReader(data))req.Header.Set("Content-Type", "application/json")setClientHeaders(req, token)+ for key, value := range headers {+ req.Header.Set(key, value)+ }resp, err := client.Do(req)if err != nil {fatal("Request failed: %v", err)diff --git a/internal/cli/output/format.go b/internal/cli/output/format.gonew file mode 100644index 00000000..79a4620f--- /dev/null+++ b/internal/cli/output/format.go@@ -0,0 +1,56 @@+package output++import (+ "encoding/json"+ "fmt"+ "os"+)++// Success prints "OK" for commands that succeeded with no payload.+func Success() {+ fmt.Println("OK")+}++// Value prints a single scalar value.+func Value(v any) {+ fmt.Println(v)+}++// Error prints an error to stderr and exits with the given code.+// Format: ERROR: <cmd>: <reason>+func Error(cmd, reason string, code int) {+ fmt.Fprintf(os.Stderr, "ERROR: %s: %s\n", cmd, reason)+ os.Exit(code)+}++// ErrorWithHint prints an error with a hint to stderr and exits.+func ErrorWithHint(cmd, reason, hint string, code int) {+ fmt.Fprintf(os.Stderr, "ERROR: %s: %s\n", cmd, reason)+ fmt.Fprintf(os.Stderr, "HINT: %s\n", hint)+ os.Exit(code)+}++// Hint prints a hint line to stderr (does not exit).+func Hint(text string) {+ fmt.Fprintf(os.Stderr, "HINT: %s\n", text)+}++// JSON prints the value as pretty-printed JSON.+func JSON(v any) {+ data, err := json.MarshalIndent(v, "", " ")+ if err != nil {+ fmt.Println(v)+ return+ }+ fmt.Println(string(data))+}++// Exit codes per the spec.+const (+ ExitSuccess = 0+ ExitUsage = 1 // bad flags, missing arg+ ExitRuntime = 2 // server returned non-2xx+ ExitNotFound = 3 // ref/selector didn't resolve+ ExitTimeout = 4 // wait/nav exceeded budget+ ExitIDPIBlocked = 5 // blocked by IDPI+)diff --git a/internal/handlers/evaluate.go b/internal/handlers/evaluate.goindex 7c43d730..40bef0d2 100644--- a/internal/handlers/evaluate.go+++ b/internal/handlers/evaluate.go@@ -9,6 +9,7 @@ import ("io""log/slog""net/http"+ "strings""github.com/chromedp/cdproto/runtime""github.com/chromedp/chromedp"@@ -72,6 +73,16 @@ func (h *Handlers) HandleEvaluate(w http.ResponseWriter, r *http.Request) {})}if err := h.evalRuntime(tCtx, req.Expression, &result, opts...); err != nil {+ errMsg := err.Error()+ // Add helpful hints for common JavaScript errors+ if strings.Contains(errMsg, "Cannot read properties of null") ||+ strings.Contains(errMsg, "Cannot read property") ||+ strings.Contains(errMsg, "null is not an object") {+ httpx.ErrorCode(w, 500, "evaluate_null_ref", fmt.Sprintf("evaluate: %s", errMsg), false, map[string]any{+ "hint": "querySelector returned null — the element doesn't exist. Use snapshot refs (e0, e1, ...) instead of raw selectors.",+ })+ return+ }httpx.Error(w, 500, fmt.Errorf("evaluate: %w", err))return}diff --git a/internal/handlers/snapshot.go b/internal/handlers/snapshot.goindex 368cdde5..c1700a55 100644--- a/internal/handlers/snapshot.go+++ b/internal/handlers/snapshot.go@@ -324,6 +324,25 @@ func (h *Handlers) HandleSnapshot(w http.ResponseWriter, r *http.Request) {if doDiff && prevNodes != nil {added, changed, removed := bridge.DiffSnapshot(prevNodes, flat)++ // Compact diff format: show all nodes with [+]/[~] markers+ if format == "compact" {+ w.Header().Set("Content-Type", "text/plain; charset=utf-8")+ w.WriteHeader(200)+ _, _ = fmt.Fprintf(w, "# %s | %s | %d nodes | +%d ~%d -%d",+ title, url, len(flat), len(added), len(changed), len(removed))+ if truncated {+ _, _ = fmt.Fprintf(w, " (truncated to ~%d tokens)", maxTokens)+ }+ _, _ = w.Write([]byte("\n"))+ content := bridge.FormatSnapshotCompactDiff(flat, added, changed, removed)+ if wrapContent {+ content = h.IDPIGuard.WrapContent(content, url)+ }+ _, _ = w.Write([]byte(content))+ return+ }+httpx.JSON(w, 200, map[string]any{"url": url,"title": title,diff --git a/internal/mcp/handlers_interaction.go b/internal/mcp/handlers_interaction.goindex c52a7702..2621c2b0 100644--- a/internal/mcp/handlers_interaction.go+++ b/internal/mcp/handlers_interaction.go@@ -3,6 +3,7 @@ package mcpimport ("context""fmt"+ "net/url""strings""github.com/mark3labs/mcp-go/mcp"@@ -163,6 +164,27 @@ func handleAction(c *Client, kind string) func(context.Context, mcp.CallToolRequif err != nil {return mcp.NewToolResultError(err.Error()), nil}+ if code >= 400 {+ return resultFromBytes(body, code)+ }++ // If snap=true, append interactive compact snapshot+ snapSupportedKinds := map[string]bool{"click": true, "fill": true, "select": true}+ if snapSupportedKinds[kind] {+ if snap, ok := optBool(r, "snap"); ok && snap {+ q := url.Values{}+ q.Set("filter", "interactive")+ q.Set("format", "compact")+ if tabID := optString(r, "tabId"); tabID != "" {+ q.Set("tabId", tabID)+ }+ snapBody, _, snapErr := c.Get(ctx, "/snapshot", q)+ if snapErr == nil {+ return mcp.NewToolResultText(string(body) + "\n" + string(snapBody)), nil+ }+ }+ }+return resultFromBytes(body, code)}}diff --git a/internal/mcp/handlers_navigation.go b/internal/mcp/handlers_navigation.goindex 364f61f5..097ac214 100644--- a/internal/mcp/handlers_navigation.go+++ b/internal/mcp/handlers_navigation.go@@ -21,13 +21,32 @@ func handleNavigate(c *Client) func(context.Context, mcp.CallToolRequest) (*mcp.return mcp.NewToolResultError("invalid URL: " + err.Error()), nil}payload := map[string]any{"url": safeURL}- if tabID := optString(r, "tabId"); tabID != "" {+ tabID := optString(r, "tabId")+ if tabID != "" {payload["tabId"] = tabID}body, code, err := c.Post(ctx, "/navigate", payload)if err != nil {return mcp.NewToolResultError(err.Error()), nil}+ if code >= 400 {+ return resultFromBytes(body, code)+ }++ // If snap=true, append interactive compact snapshot+ if snap, ok := optBool(r, "snap"); ok && snap {+ q := url.Values{}+ q.Set("filter", "interactive")+ q.Set("format", "compact")+ if tabID != "" {+ q.Set("tabId", tabID)+ }+ snapBody, _, snapErr := c.Get(ctx, "/snapshot", q)+ if snapErr == nil {+ return mcp.NewToolResultText(string(body) + "\n" + string(snapBody)), nil+ }+ }+return resultFromBytes(body, code)}}diff --git a/internal/mcp/tools.go b/internal/mcp/tools.goindex dc794475..6322821c 100644--- a/internal/mcp/tools.go+++ b/internal/mcp/tools.go@@ -10,6 +10,7 @@ func allTools() []mcp.Tool {mcp.WithDescription("Navigate to a URL in the browser"),mcp.WithString("url", mcp.Required(), mcp.Description("The URL to navigate to")),mcp.WithString("tabId", mcp.Description("Target tab ID (optional, uses current tab if empty)")),+ mcp.WithBoolean("snap", mcp.Description("Return interactive compact snapshot after navigation (saves a round-trip)")),),mcp.NewTool("pinchtab_snapshot",mcp.WithDescription("Get an accessibility tree snapshot of the current page. Use this sparingly: prefer pinchtab_find + action selectors for faster loops."),@@ -56,6 +57,7 @@ func allTools() []mcp.Tool {mcp.WithNumber("y", mcp.Description("Optional Y coordinate for coordinate click")),mcp.WithNumber("nodeId", mcp.Description("Optional backend node ID to target directly")),mcp.WithBoolean("waitNav", mcp.Description("Wait for navigation after the click when the element triggers a page change")),+ mcp.WithBoolean("snap", mcp.Description("Return interactive compact snapshot after click (saves a round-trip)")),mcp.WithString("tabId", mcp.Description("Target tab ID")),),mcp.NewTool("pinchtab_type",@@ -96,6 +98,7 @@ func allTools() []mcp.Tool {mcp.WithString("query", mcp.Description("Alias for semantic targeting when selector is omitted")),mcp.WithString("value", mcp.Required(), mcp.Description("Option value or visible text to select")),mcp.WithString("tabId", mcp.Description("Target tab ID")),+ mcp.WithBoolean("snap", mcp.Description("Return interactive compact snapshot after select (saves a round-trip)")),),mcp.NewTool("pinchtab_scroll",mcp.WithDescription("Scroll the page or an element. For element targeting + pixel deltas, this automatically uses wheel semantics for smoother behavior."),@@ -125,6 +128,7 @@ func allTools() []mcp.Tool {mcp.WithString("query", mcp.Description("Alias for semantic targeting when selector is omitted")),mcp.WithString("value", mcp.Required(), mcp.Description("Value to fill")),mcp.WithString("tabId", mcp.Description("Target tab ID")),+ mcp.WithBoolean("snap", mcp.Description("Return interactive compact snapshot after fill (saves a round-trip)")),),// ── Keyboard (no selector — targets focused element) ────────diff --git a/skills/pinchtab/SKILL.md b/skills/pinchtab/SKILL.mdindex bc23f1b4..03b93e59 100644--- a/skills/pinchtab/SKILL.md+++ b/skills/pinchtab/SKILL.md@@ -23,314 +23,193 @@ metadata:# Browser Automation with PinchTab-PinchTab gives agents a browser they can drive through stable accessibility refs, low-token text extraction, and persistent profiles or instances. Treat it as a CLI-first browser skill; use the HTTP API only when the CLI is unavailable or you need profile-management routes that do not exist in the CLI yet.--Preferred tool surface:--- Use `pinchtab` CLI commands first.-- Use `curl` for profile-management routes or non-shell/API fallback flows.-- Use `jq` only when you need structured parsing from JSON responses.+CLI-first browser skill. Use `pinchtab` commands.## Core Workflow-Every PinchTab automation follows this pattern:+1. Ensure the right server/profile/instance is active.+2. Navigate: `pinchtab nav <url> --snap` — returns tab ID + interactive snapshot in one call.+3. Interact: `pinchtab click <ref> --snap-diff` — returns OK + only changed elements (most token-efficient).+4. For read-only observation: `pinchtab text` when you won't act on refs.-1. Ensure the correct server, profile, or instance is available for the task.-2. Navigate with `pinchtab nav <url>` or `pinchtab instance navigate <instance-id> <url>`.-3. Observe with `pinchtab snap -i -c` (interactive refs, smaller), `pinchtab snap -c` (refs + body content), or `pinchtab text` (content only). Collect refs such as `e5`.-4. Interact with those fresh refs using `click`, `fill`, `type`, `press`, `select`, `hover`, or `scroll`.-5. Re-snapshot or re-read text after any navigation, submit, modal open, accordion expand, or other DOM-changing action.+**Key optimization**: Use `--snap-diff` on `click`, `fill`, `select`, `back`, `forward`, `reload` to get only added/changed/removed elements — most token-efficient for multi-step flows. Use `--snap` when you need the full snapshot (e.g., first navigation, or after major page changes). Use `--text` when you need prose content for verification (skips snap, returns page text directly).-Rules:+`--snap-diff` returns the same compact format as `snap`, but with change markers and a header showing counts:+```+# Page Title | URL | 57 nodes | +2 ~1 -0+e0:link "Home"+e5:button "Submit" [+]+e12:textbox val="updated" [~]+# removed: e99+```+`[+]` = added, `[~]` = changed, removed refs listed at end. All valid refs are shown — no need to remember previous snapshot. Do not follow with redundant `snap`; only call `text` when you need prose content.-- Never act on stale refs after the page changes.-- Default to `pinchtab snap -i -c` for most observations — it returns only interactive elements and is smaller/faster.-- Use `pinchtab snap -c` (no `-i`) only when you need **both** refs and body content in one call — e.g. verifying a success message after form submit.-- Default to `pinchtab text` when you need content only and won't act on refs from the same observation.-- Use screenshots only for visual verification, UI diffs, or debugging.-- Start multi-site or parallel work by choosing the right instance or profile first.+Fallback observation (when `--snap` wasn't used):+- `pinchtab snap` — interactive elements + headings in compact format (default).+- `pinchtab snap --full` — all nodes as JSON (for debugging).+- `pinchtab text` — content only (use when snap is missing prose you need).-## Selectors+Rules: never act on stale refs; screenshots only for visual/debug; choose the instance/profile up front for parallel or multi-site work.-PinchTab uses a unified selector system. Any command that targets an element accepts these formats:+## Selectors-| Selector | Example | Resolves via |-|---|---|---|-| Ref | `e5` | Snapshot cache (fastest) |-| CSS | `#login`, `.btn`, `[data-testid="x"]` | `document.querySelector` |-| XPath | `xpath://button[@id="submit"]` | CDP search |-| Text | `text:Sign In` | Visible text match |-| Semantic | `find:login button` | Natural language query via `/find` |+Unified selectors accepted by any element-targeting command:-Auto-detection: bare `e5` → ref, `#id` / `.class` / `[attr]` → CSS, `//path` → XPath. Use explicit prefixes (`css:`, `xpath:`, `text:`, `find:`) when auto-detection is ambiguous.+- Ref: `e5` — from snapshot cache (fastest).+- CSS: `#login`, `.btn`, `[data-testid="x"]` — `document.querySelector`.+- XPath: `xpath://button[@id="submit"]` — CDP search.+- Text: `text:Sign In` — visible text match.+- Semantic: `find:login button` — natural language via `/find`.-```bash-pinchtab click e5 # ref-pinchtab click "#submit" # CSS (auto-detected)-pinchtab click "text:Sign In" # text match-pinchtab click "xpath://button[@type]" # XPath-pinchtab fill "#email" "[email protected]" # CSS-pinchtab fill e3 "[email protected]" # ref-```--Same syntax in HTTP API via `selector` field. Legacy `ref` field still accepted.+Auto-detection: bare `eN`→ref, `#`/`.`/`[...]`→CSS, `//`→XPath. Use explicit `css:`/`xpath:`/`text:`/`find:` prefixes when ambiguous. HTTP API uses the same syntax in the `selector` field (legacy `ref` still accepted).## Command Chaining-Use `&&` when you don't need intermediate output: `pinchtab nav <url> && pinchtab snap -i -c`. Run separately when you must read refs before acting.+`&&` when you don't need intermediate output (`pinchtab nav <url> --snap && pinchtab click e3 --snap-diff`). Run separately when you must read refs before acting.## Challenge Solving-If a page shows a challenge instead of content (e.g., "Just a moment..."), call `POST /solve` with `{"maxAttempts": 3}` to auto-detect and resolve it. Use `POST /tabs/TAB_ID/solve` for tab-scoped. Works best with `stealthLevel: "full"` in config. Safe to call speculatively — returns immediately if no challenge is present. See [api.md](./references/api.md) for full solver options.--## Handling Authentication and State+Pages showing "Just a moment..." etc.: `POST /solve {"maxAttempts":3}` (or `/tabs/TAB_ID/solve`). Best with `stealthLevel:"full"`. Safe to call speculatively — returns immediately if no challenge. See [api.md](./references/api.md).-Patterns: (1) One-off: `pinchtab instance start` → `--server http://localhost:<port>`. (2) Reuse profile: `pinchtab instance start --profile work --mode headed` → switch to headless after login. (3) HTTP: `POST /profiles`, then `POST /profiles/<name>/start`. (4) Human-assisted: headed login, then agent reuses headless.+## Authentication and State-Agent sessions: `pinchtab session create --agent-id <id>` or `POST /sessions` → set `PINCHTAB_SESSION=ses_...`.+Patterns: (1) one-off `pinchtab instance start`; (2) reuse profile `instance start --profile work --mode headed`, switch to headless after login; (3) HTTP `POST /profiles` then `POST /profiles/<name>/start`; (4) human-assisted headed login, agent reuses headless. Agent sessions: `pinchtab session create --agent-id <id>` or `POST /sessions` → set `PINCHTAB_SESSION=ses_...`.## Essential Commands### Server and targeting```bash-pinchtab server # Start server foreground-pinchtab daemon install # Install as system service-pinchtab health # Check server status-pinchtab instances # List running instances-pinchtab profiles # List available profiles-pinchtab --server http://localhost:9868 snap -i -c # Target specific instance+pinchtab server | daemon install | health+pinchtab instances | profiles+pinchtab --server http://localhost:9868 snap -i -c # target a specific instance```### Navigation and tabs```bash-pinchtab nav <url>-pinchtab nav <url> --new-tab-pinchtab nav <url> --tab <tab-id>-pinchtab nav <url> --block-images-pinchtab nav <url> --block-ads-pinchtab nav <url> --print-tab-id # Print only the new tabId on stdout-pinchtab back # Navigate back in history-pinchtab forward # Navigate forward-pinchtab reload # Reload current page-pinchtab tab # List tabs (no subcommand - just `tab`)-pinchtab tab <tab-id> # Focus an existing tab-pinchtab tab new <url> # Open a new tab-pinchtab tab close <tab-id> # Close a tab — use this to clean up stale tabs between runs+pinchtab nav <url> # flags: --snap, --new-tab, --tab <id>, --block-images, --block-ads, --print-tab-id+pinchtab back | forward | reload # all support --snap, --snap-diff, --text+pinchtab tab # list tabs+pinchtab tab <tab-id> # focus tab+pinchtab tab new <url> | tab close <tab-id>pinchtab instance navigate <instance-id> <url>```-**Tab workflow** — most commands target the active tab by default, so single-tab flows need no plumbing:-```bash-pinchtab nav http://example.com-pinchtab snap -i -c # active tab-pinchtab click e5 # active tab-pinchtab text # active tab-```--When you need to pin to a specific tab (parallel tabs, long-running flows, or shell-isolated-runners like agent tool calls where env vars don't persist across invocations), capture the-tab ID with `--print-tab-id` and pass `--tab` on every subsequent command:-```bash-TAB_ID=$(pinchtab nav http://example.com --print-tab-id)-pinchtab --tab "$TAB_ID" snap -i -c-pinchtab --tab "$TAB_ID" click e5-pinchtab --tab "$TAB_ID" text-```--Within a single shell session you can also `export PINCHTAB_TAB=$(pinchtab nav URL --print-tab-id)`-and drop the `--tab` flag. This does **not** survive across separate shell invocations (each-`Bash` tool call in an agent runs a fresh shell), so prefer explicit `--tab` for agent workflows.--Priority: `--tab <id>` flag > `PINCHTAB_TAB` env var > active tab.+Tab state is automatic: `nav` persists the tab ID to a state file, and subsequent commands read it. No need for `export PINCHTAB_TAB=...` boilerplate. Just run `pinchtab nav URL` then `pinchtab snap -i -c` — the tab is remembered. For explicit control: `--tab <id>` flag or `PINCHTAB_TAB` env var override the state file.### Observation```bash-pinchtab snap-pinchtab snap -i # Interactive elements only-pinchtab snap -i -c # Interactive + compact-pinchtab snap -d # Diff from previous snapshot-pinchtab snap --selector <css> # Scope to CSS selector-pinchtab snap --max-tokens <n> # Token budget limit-pinchtab snap --text # Text output format-pinchtab text # Page text content (Readability-filtered; drops nav/repeated headlines)-pinchtab text --full # Full page text (document.body.innerText) — use when Readability is dropping content you need-pinchtab text --raw # Alias of --full-pinchtab text e5 # Extract text from element by ref-pinchtab text -s "#article" # Extract text from element by CSS selector-pinchtab text "xpath://div[@class='content']" # Extract text from element by XPath-# CLI returns JSON; use `| jq -r .text` for plain text-pinchtab find <query> # Semantic element search-pinchtab find --ref-only <query> # Return refs only+pinchtab snap # default: compact + interactive; flags: --full (JSON), -d (diff), --selector <css>, --max-tokens <n>+pinchtab text # Readability-filtered page text+pinchtab text --full # raw document.body.innerText (alias: --raw)+pinchtab text <selector> # ref / -s CSS / xpath:... — text from one element+pinchtab text --json # full JSON (url/title/truncated)+pinchtab find <query> # semantic search; --ref-only for just the ref```Guidance:-- **`snap -i -c`** is the default for most observations. It returns only interactive elements- (links, buttons, inputs, etc.) in compact form — smaller output, faster to parse.- Use this after navigation, DOM changes, or when you need fresh refs to act on.-- **`snap -c` (no `-i`)** is for when you need refs **and** body content in one call.- The compact output includes headings, paragraphs, and landmarks alongside interactive refs.- Use this for verification steps ("did the success banner appear?") or initial page orientation- when you need to read content and act in the same observation.-- `snap -d` is the default follow-up snapshot for multi-step flows.-- `text` is the default for reading articles, dashboards, reports, or confirmation messages- when you have no reason to act on refs from the same observation.-- `text <selector>` extracts text from a specific element — use it to read a single card,- table cell, or status message without pulling the entire page.-- **`pinchtab find <query>`** is the direct route when you already know the semantic target- (e.g. "login button", "email input", "accept cookies link") — skips the full snapshot and- returns a ranked match with its ref. Pair with `--ref-only` on large/dense pages to get just- the ref string for piping straight into `click` / `fill` / `type`. Prefer `find` over- `snap -i -c` + visual scan whenever you can describe the target in a phrase.-- Refs from `snap -i` and full `snap` use different numbering. Do not mix them — if you snapshot with `-i`, use those refs. If you re-snapshot without `-i`, get fresh refs before acting.+- `snap` — default observation (compact + interactive). Returns interactive elements + headings. Prefer this over separate `text` calls.+- `snap --full` — all nodes as JSON; for debugging or when you need the full tree.+- `snap -d` — standalone diff from previous snapshot. Use only when you need a diff without performing an action; for any click/fill/select/back/forward/reload, `--snap-diff` on the action itself already gives you the authoritative post-action state.+- `text` — reading articles/dashboards when you won't act on refs. Falls back to `--full` when Readability drops content you need.+- `text <selector>` — read one element without pulling the whole page.+- `find <query>` — skip the snapshot when you can describe the target in a phrase. `--ref-only` pipes straight into `click`/`fill`/`type`.+- Refs from `snap -i` and full `snap` are numbered differently — do not mix; re-snapshot before acting if you switched modes.+- Use `--block-images` on `nav` for read-heavy tasks. Reserve screenshots/PDFs for visual verification.### Interaction-All interaction commands accept unified selectors (refs, CSS, XPath, text, semantic). See the Selectors section above.+All interaction commands accept unified selectors (see Selectors above).```bash-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 click <selector> --dialog-action accept # Click + auto-accept any alert/confirm the click opens-pinchtab click <selector> --dialog-action dismiss # Click + auto-dismiss-pinchtab click <selector> --dialog-action accept \- --dialog-text "hello" # Click + accept a prompt() with a response-pinchtab dblclick <selector> # Double-click element-pinchtab mouse move <selector> # Move pointer to element center-pinchtab mouse move <x> <y> # Move pointer to coordinates-pinchtab mouse down <selector> --button left # Press a mouse button at an explicit target-pinchtab mouse down --button left # Press a mouse button at current pointer-pinchtab mouse up <selector> --button left # Release a mouse button at an explicit target-pinchtab mouse up --button left # Release a mouse button at current pointer-pinchtab mouse wheel 240 --dx 40 # Dispatch wheel deltas at current pointer-pinchtab drag <from> <to> # Drag between selector/ref or x,y points (synthesized mouse sequence)-pinchtab drag <selector> --drag-x <n> --drag-y <n> # Single-step drag by pixel offset (mirrors HTTP /action dragX/dragY)-pinchtab type <selector> <text> # Type with keystrokes-pinchtab fill <selector> <text> # Set value directly-pinchtab press <key> # Press key (Enter, Tab, Escape...)-pinchtab hover <selector> # Hover element-pinchtab select <selector> <value|text> # Select dropdown option by value attr, or fall back to visible text-pinchtab scroll <pixels|direction|selector> # e.g. `scroll 1500`, `scroll down`, `scroll '#footer'`+pinchtab click <selector> # flags: --snap, --snap-diff, --text, --wait-nav, --x/--y (coords), --dialog-action accept|dismiss [--dialog-text "..."]+pinchtab dblclick <selector>+pinchtab mouse move|down|up <selector|x y> # --button left|middle|right+pinchtab mouse wheel <ms> --dx <n> --dy <n>+pinchtab drag <from> <to> # or: drag <selector> --drag-x <n> --drag-y <n>+pinchtab type <selector> <text> # keystroke events+pinchtab fill <selector> <text> # set value directly; flags: --snap, --snap-diff, --text+pinchtab press <key> # Enter, Tab, Escape, ...+pinchtab hover <selector>+pinchtab select <selector> <value|text> # flags: --snap, --snap-diff, --text; matches value attr, falls back to visible text+pinchtab scroll <pixels|direction|selector> # `scroll 1500`, `scroll down`, `scroll '#footer'````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.-- `select` matches by value attr first, then visible text (case-insensitive). Error lists available options if no match.-- For JS dialogs: use `--dialog-action accept` or `--dialog-action dismiss` on click. Add `--dialog-text` for prompt responses.-- For the `scroll` action via HTTP, use `"scrollX"` / `"scrollY"` for pixel deltas, or `"selector"` to scroll an element into view. Example: `{"kind":"scroll","scrollY":1500}` or `{"kind":"scroll","selector":"#footer"}`. The `x`/`y` fields are target viewport coordinates, not scroll deltas.-- The download HTTP endpoint (`GET /download?url=...` or `GET /tabs/TAB_ID/download?url=...`) returns JSON `{contentType, data (base64), size, url}`, not raw bytes. Decode `data` with base64 to get the file. Only `http`/`https` URLs are allowed. Private/internal hosts are blocked unless listed in `security.downloadAllowedDomains`.+- Default output is `OK`; use `--json` for recovery metadata. Errors go to stderr as `ERROR: <cmd>: <reason>`.+- **Prefer `--snap-diff`** with `click`, `fill`, `select`, `back`, `forward`, `reload` — returns `OK` + only changed elements. Use `--snap` when you need the full snapshot (first nav, major page change).+- Prefer `fill` for form entry; `type` only when the site depends on keystroke events.+- `click --wait-nav` when a click navigates. May return `{"success":true}` or `Error 409: unexpected page navigation` — treat 409 as success and verify with fresh `snap`/`text`.+- Use low-level `mouse` only for drag handles, canvas widgets, or exact pointer sequences.+- JS dialogs: `--dialog-action accept|dismiss`, `--dialog-text` for `prompt()` responses.+- HTTP scroll action: `"scrollX"`/`"scrollY"` for pixel deltas, `"selector"` to scroll into view — `x`/`y` are viewport coords, not deltas.+- HTTP `GET /download?url=...` returns JSON `{contentType, data (base64), size, url}`; only http/https; private/internal hosts blocked unless in `security.downloadAllowedDomains`.### Waiting-Use `wait` when the DOM settles asynchronously — spinners, toasts, XHR-driven content.+Use for async DOM settling (spinners, toasts, XHR).```bash-pinchtab wait <selector> # Element to appear (default visible)-pinchtab wait <selector> --state hidden # Element to disappear-pinchtab wait --text "Order confirmed" # Text to appear-pinchtab wait --not-text "Loading..." # Text to disappear (spinner/toast dismiss)-pinchtab wait --url "**/dashboard" # URL glob match-pinchtab wait --load networkidle # Network idle-pinchtab wait 500 # Fixed delay in ms (last resort)+pinchtab wait <selector> # default: visible; --state hidden to wait for disappear+pinchtab wait --text "..." | --not-text "..." # text appear / disappear+pinchtab wait --url "**/dashboard" | --load networkidle+pinchtab wait 500 # fixed ms delay (last resort)```-Default timeout 10s, max 30s via `--timeout <ms>`. Prefer `--not-text` / `--state hidden` over polling.+Timeout 10s default, 30s max via `--timeout <ms>`. Prefer `--not-text`/`--state hidden` over polling.-### Export, debug, and verification+### Export, debug, verification```bash-pinchtab screenshot-pinchtab screenshot -o /tmp/pinchtab-page.png # Format driven by extension-pinchtab screenshot -q 60 # JPEG quality-pinchtab pdf-pinchtab pdf -o /tmp/pinchtab-report.pdf-pinchtab pdf --landscape+pinchtab screenshot [-o path.png] [-q <jpeg-quality>] # format by extension+pinchtab pdf [-o path.pdf] [--landscape]```-### Advanced operations: explicit opt-in only--Use these only when the task explicitly requires them and safer commands are insufficient.+### Advanced (explicit opt-in only)```bash-pinchtab eval "document.title"-pinchtab eval --await-promise "fetch('/api/me').then(r => r.json())"-pinchtab download <url> -o /tmp/pinchtab-download.bin-pinchtab upload /absolute/path/provided-by-user.ext -s <css>+pinchtab eval "document.title" # --await-promise for async+pinchtab download <url> -o /tmp/out.bin+pinchtab upload /absolute/path -s <css>```-Rules:--- `eval` is for narrow, read-only DOM inspection unless the user explicitly asks for a page mutation.-- `download` should prefer a safe temporary or workspace path over an arbitrary filesystem location.-- `upload` requires a file path the user explicitly provided or clearly approved for the task.+- `eval`: narrow read-only DOM inspection unless user asks for mutation.+- `download`: prefer temp/workspace path over arbitrary filesystem.+- `upload`: path must be user-provided or clearly approved.### HTTP API fallback-Use curl when CLI unavailable. Key endpoints on instance port (e.g. 9867):-- `POST /navigate` with `{"url":"..."}`-- `GET /snapshot?filter=interactive&format=compact`-- `POST /action` with `{"kind":"fill","selector":"e3","text":"..."}`-- `POST /actions` with a batch of actions — runs them in one round-trip. Body accepts either- an array `[{"kind":"fill",...},{"kind":"click",...}]` or an envelope- `{"actions":[...],"stopOnError":true,"tabId":"..."}`. Use this for tight form flows (fill +- fill + click submit) to cut round-trip latency. Set `stopOnError:true` to halt on the first- failure; the response contains a per-step `{index, success, result?, error?}` array.- Tab-scoped variant: `POST /tabs/TAB_ID/actions`.-- `GET /text`-- `POST /solve` with `{"maxAttempts": 3}`--### Tab-scoped HTTP API--Use `/tabs/TAB_ID/...` routes to target specific tabs. Get tab ID from navigate response or `GET /tabs`.--Pattern: `curl -H "Authorization: Bearer <token>" http://localhost:9867/tabs/TAB_ID/<endpoint>`+Use curl only when CLI is unavailable. Instance port (e.g. 9867):-Key endpoints: `navigate`, `snapshot`, `text`, `action`, `screenshot`, `pdf`, `back`, `forward`, `close`, `wait`, `download`, `upload`, `handoff`, `resume`.--Action examples:-- Click: `{"kind":"click","selector":"#btn"}`-- Click with nav: `{"kind":"click","selector":"#link","waitNav":true}`-- Drag: `{"kind":"drag","selector":"#piece","dragX":12,"dragY":-158}`-- Scroll: `{"kind":"scroll","scrollY":1500}` or `{"kind":"scroll","selector":"#footer"}`+- `POST /navigate` `{"url":"..."}`+- `GET /snapshot?filter=interactive&format=compact`+- `POST /action` `{"kind":"fill","selector":"e3","text":"..."}` — kinds: click (`waitNav:true`), fill, type, press, select, hover, scroll (`scrollX`/`scrollY`/`selector`), drag (`dragX`/`dragY`).+- `POST /actions` — batch in one round-trip. Body: array or `{"actions":[...],"stopOnError":true,"tabId":"..."}`. Response has per-step `{index, success, result?, error?}`.+- `GET /text`, `POST /solve` `{"maxAttempts":3}`.+- Tab-scoped: `/tabs/TAB_ID/<endpoint>` for `navigate|snapshot|text|action|actions|screenshot|pdf|back|forward|close|wait|download|upload|handoff|resume|solve`. Auth: `Authorization: Bearer <token>`.## Common Patterns-- **Form flow**: `nav` → `snap -i -c` (refs for form fields) → `fill` fields → `click --wait-nav` submit → `snap -i -c` + `text` or `snap -c` (to verify success message). Use `snap -c` only when you need refs and body content in the same call.-- **Multi-step**: After each action, `snap -d -i -c` for diff-- **Direct selectors**: Skip snapshot when structure is known: `pinchtab click "text:Accept Cookies"` or `fill "#search" "query"`--**Form submission:** Always click the submit button — never use `press Enter`.--## Token Economy--Prefer low-token commands: `snap -i -c` (default), `text`, `snap -d`. Use `--block-images` for read-heavy tasks. Reserve screenshots/PDFs for visual verification.--**Always use `-i` with `snap`** unless you specifically need body content (headings, paragraphs) in the same call. Without `-i`, the full accessibility tree includes redundant StaticText nodes that inflate token usage.--## Diffing and Verification--- Use `pinchtab snap -d` after each state-changing action in long workflows.-- Use `pinchtab text` to confirm success messages, table updates, or navigation outcomes. The default mode extracts Readability-filtered content (reader view), which may drop navigation, repeated headlines, short-text nodes, or collapse lists/grids down to a single representative item. Reach for `pinchtab text --full` whenever (a) you're verifying content on a list/grid/tab/accordion page, (b) the expected marker is short, or (c) a default read came back missing content you can see in the snapshot. It returns the raw `document.body.innerText` and is almost always the safer choice once you know Readability is going to trim.-- Use `pinchtab screenshot` only when visual regressions, CAPTCHA, or layout-specific confirmation matters.-- If a ref disappears after a change, treat that as expected and fetch fresh refs instead of retrying the stale one.-- Action responses like `{"clicked":true,"submitted":true}` mean the event fired on the target element — **not** that the form was accepted by the server or passed native HTML validation. Always verify the expected success marker or state change via `snap`/`text` before treating a submission as complete.-- **Same-origin iframes** are supported natively via `pinchtab frame <target>` — a stateful scope that subsequent selector-based `/snapshot` and `/action` calls inherit. Typical flow: `pinchtab frame '#payment-frame'` → `pinchtab snap -i -c` (refs reflect iframe interior) → `pinchtab fill '#card'` / `click '#pay'` → `pinchtab frame main`. Target accepts `main`, an iframe ref, a CSS selector for the iframe element, a frame name, or a frame URL. Nested iframes need multiple hops. Refs emitted by a full `snap` (no `-i`) for iframe descendants carry frame context — ref-based actions work across the boundary without an explicit scope set. **Cross-origin iframes** are not exposed as frame scopes; fall back to `eval` against `iframe.contentDocument` (same-origin-policy permitting). `pinchtab text` (and `text --full`) honors the active frame scope and also accepts an explicit `--frame <frameId>` flag for one-shot reads — so after `pinchtab frame '#content-frame'`, a following `pinchtab text --full` extracts from the iframe's document, not the outer page. **The `--frame` argument must be a frame ID (the 32-char hex `frameId` from `pinchtab frame <target>` output), not a CSS selector.** For a one-shot read, the idiom is: `FID=$(pinchtab frame '#content-frame' | jq -r .current.frameId); pinchtab frame main; pinchtab text --full --frame "$FID"`. Passing a selector like `text --frame '#content-frame'` returns "no frame for given id found".-- **`eval` → always IIFE.** `eval` expressions share the same realm across calls, so any top-level `const`/`let`/`class` from one call collides with the next: `SyntaxError: Identifier 'x' has already been declared`. Use an IIFE on every `eval` that introduces identifiers, not only on multi-statement ones: `pinchtab eval "(() => { const r = document.querySelector('#x').getBoundingClientRect(); return {x: r.x, y: r.y, w: r.width, h: r.height}; })()"`. For a single expression that doesn't introduce identifiers (e.g. `document.title`, `document.getElementById('x').value`), the IIFE is optional. The IIFE pattern also fixes DOMRect serialization — `getBoundingClientRect()` returns a value whose own-enumerable fields don't survive JSON, so the explicit projection is what actually ships the numbers back.-- **`pinchtab text` (both default and `--full`) returns content from `display:none` and `visibility:hidden` nodes** because it reads `document.body.innerText` (and Readability's input) from raw DOM — the visibility cascade is not applied. When you need to confirm that a success banner or error message is *actually visible* (not just present as a pre-seeded hidden element), verify via `pinchtab snap` (the accessibility tree respects visibility and hides non-rendered subtrees) or via `eval` against the element's `offsetHeight` / `getComputedStyle().display`. A common trap: a page ships with a hidden success `<div>` pre-rendered; `text` will report the success string before the form is ever submitted.-- The compact snapshot shows `<option>` elements by their visible text, not their `value` attribute. You don't normally need to look up the `value`: the `select` action accepts either — it matches on `value` first and falls back to visible text (case-insensitive). Only reach for `eval` + `Array.from(select.options)` when debugging an unexpected no-match error.-- `text:<value>` selectors are resolved by a JS-level search over visible text and can intermittently fail with `DOM Error` or `context deadline exceeded` on large/dynamic pages. If you have a fresh `snap -i -c` in hand, prefer the ref (`e12`) — refs resolve by stable backend node IDs and don't depend on page-side JS.-- `snap -i -c` (interactive, compact) skips non-interactive descendants. For iframe interiors, either set a `frame` scope first or use a full `pinchtab snap` (no `-i`) which flattens same-origin iframe descendants into the parent snapshot.-- ARIA expansion state (`aria-expanded="true" | "false"`) is usually placed on the **outermost container** of an accordion/menu/disclosure section, not on the header/trigger that dispatches the click. When verifying state after a click, query `document.querySelector('#section-a').getAttribute('aria-expanded')` (or the wrapper's equivalent) rather than the clicked element.-- `click --wait-nav` can return `{"success": true}` or, immediately after the navigation fires, `Error 409: unexpected page navigation` — the latter means the server saw a navigation while mid-response and aborted its reply, not that the click failed. Treat 409 after a navigation-expected click as success and verify the resulting page with a fresh `snap` / `text`.+- **Form**: `nav --snap` → `fill <ref> <text> --snap-diff` per field → `click --wait-nav --snap-diff` submit → verify with `text`. Always click submit; never `press Enter`.+- **Multi-step**: use `click --snap-diff` to get only changed refs with each action — most token-efficient for flows with many steps.+- **Direct selectors**: skip the snapshot when structure is known — `click "text:Accept"`, `fill "#search" "q"`.++## Verification & Gotchas++- `text` confirms success messages / navigation outcomes. Default is Readability-filtered; may drop nav, repeated headlines, short-text nodes, or collapse lists. Use `text --full` (raw `document.body.innerText`) when verifying list/grid/tab/accordion pages, the marker is short, or a default read came back missing content you saw in `snap`.+- Stale refs after a change are expected — fetch fresh refs instead of retrying.+- `{"clicked":true,"submitted":true}` means the event fired, **not** that the server accepted or HTML validation passed. Verify via `snap`/`text` — or use `--snap-diff` on the action itself, which already reflects the post-event page state.+- **Same-origin iframes**: `pinchtab frame <target>` sets a stateful scope inherited by subsequent selector-based `snap`/action/text calls. Target accepts `main`, an iframe ref, CSS for the iframe, a frame name, or a URL. Nested iframes need multiple hops. Full `snap` (no `-i`) flattens same-origin iframe descendants and ref-based actions work across the boundary. **Cross-origin iframes** aren't exposed as scopes — fall back to `eval` against `iframe.contentDocument`. `text --frame <frameId>` takes a 32-char hex `frameId` (from `pinchtab frame` output), not a CSS selector. One-shot read idiom: `FID=$(pinchtab frame '#f' | jq -r .current.frameId); pinchtab frame main; pinchtab text --full --frame "$FID"`.+- **`eval` → always IIFE** when introducing identifiers. Top-level `const`/`let`/`class` collide across calls in the shared realm (`SyntaxError: Identifier 'x' has already been declared`). Also needed to project `DOMRect` into a JSON-serializable object: `pinchtab eval "(() => { const r = document.querySelector('#x').getBoundingClientRect(); return {x: r.x, y: r.y, w: r.width, h: r.height}; })()"`. Single expressions without identifiers (`document.title`) are fine bare.+- **`text` reads hidden nodes**: both default and `--full` include `display:none` / `visibility:hidden` content because they read raw DOM. To confirm something is *actually visible*, use `snap` (accessibility tree respects visibility) or `eval` against `offsetHeight` / `getComputedStyle().display`. Common trap: pre-seeded hidden success `<div>` reported by `text` before submission.+- Compact snap shows `<option>` by visible text, not `value`. `select` accepts either; only `eval + Array.from(select.options)` to debug a no-match.+- `text:<value>` selectors use JS-level search and can flake with `DOM Error` / `context deadline exceeded` on large pages. Prefer refs from a fresh `snap -i -c` — they resolve by backend node IDs.+- `snap -i -c` skips non-interactive descendants. For iframe interiors set a frame scope or use full `snap`.+- `aria-expanded` is usually on the **outer container** of accordions/menus, not the click trigger. Verify via the wrapper's attribute.## Referencesdiff --git a/skills/pinchtab/references/agent-optimization.md b/skills/pinchtab/references/agent-optimization.mdindex 3d4d6be3..429f80e3 100644--- a/skills/pinchtab/references/agent-optimization.md+++ b/skills/pinchtab/references/agent-optimization.md@@ -35,22 +35,33 @@ Need to check page state?## Diff Snapshots for Follow-Up Reads-After an interaction, use `snap -d` to see only what changed — not the full tree.+Use `--snap-diff` on action commands to get all refs plus change markers — in one call, not two.```bash-pinchtab click e5 # trigger action-pinchtab snap -d # only the delta — much smaller+pinchtab click e5 --snap-diff # action + full refs with diff markers+pinchtab fill e3 "text" --snap-diff```-**When to use `-d`:**+Output format shows all valid refs with change markers:+```+# Page | URL | 57 nodes | +2 ~1 -0+e0:link "Home"+e5:button "Submit" [+] # added+e12:textbox val="updated" [~] # changed+# removed: e99+```++**When to use `--snap-diff`:**- After clicks that update part of the UI (e.g. accordion opens, toast appears)-- After form submissions that show inline validation+- After form fills that show inline validation- During multi-step wizards where only one section changes+- Any interaction where you need to see the result — you get all refs plus diff info++**When NOT to use `--snap-diff`:**+- After `nav` to a new URL (diff would mark everything as added — use `--snap` instead)+- First snapshot of a session (no baseline exists — use `--snap`)-**When NOT to use `-d`:**-- After full page navigations (diff will be the entire new page)-- After `nav` — always take a fresh `snap` instead-- First snapshot of a session (no baseline exists)+**Fallback:** If you already performed an action without `--snap-diff`, use `snap -d` separately.---@@ -127,7 +138,7 @@ pinchtab snap -i -c # fresh snapshot → new refs# Now use the new refs from this response```-**Prevention:** Never cache refs across navigations. Always re-snap after a page load or major DOM update.+**Prevention:** Use `--snap-diff` on actions to get updated refs with each interaction. Never cache refs across navigations.---@@ -166,8 +177,9 @@ pinchtab nav <url> --block-images --timeout 60## General Efficiency Rules+- **Use `--snap-diff` on actions.** `click e5 --snap-diff` returns OK + only changed elements in one call — most token-efficient for multi-step flows.- **Set a stable agent ID up front.** Use `pinchtab --agent-id <agent-id> ...`, `PINCHTAB_AGENT_ID`, or `X-Agent-Id` for raw HTTP calls so work stays attributable to the same agent.-- **Batch reads before writes.** Snap once, extract all refs, then act. Avoid snap → act → snap → act loops when you can snap → act × N → snap once to verify.+- **Batch reads before writes.** Snap once, extract all refs, then act. Use `--snap-diff` on each action to see changes without re-fetching the full tree.- **Use `text` for extraction tasks.** If you only need to read content (not interact), `text` is cheaper than `snap` + parsing.- **Scope snapshots.** Use `snap -s <selector>` to target a specific section of the page when you know where the element is.- **Prefer `fill` over `type` for framework forms.** Saves retries caused by React/Vue not detecting raw keystroke events.diff --git a/skills/pinchtab/references/commands.md b/skills/pinchtab/references/commands.mdindex c8811447..0dfffdbd 100644--- a/skills/pinchtab/references/commands.md+++ b/skills/pinchtab/references/commands.md@@ -64,6 +64,8 @@ Click an element by its accessibility ref (from `snap`).```bashpinchtab click e5+pinchtab click e5 --snap-diff # click + return only changed elements+pinchtab click e5 --snap # click + return full snapshotpinchtab click e5 --tab <tabId>```@@ -79,6 +81,7 @@ Fill a form field using JS event dispatch. Prefer over `type` for React/Vue/Angu```bashpinchtab fill e12 "hello world"+pinchtab fill e12 "hello" --snap-diff # fill + return only changed elements```### `pinchtab press <key>`@@ -124,6 +127,7 @@ Select an option from a `<select>` dropdown.```bashpinchtab select e8 "option-value"+pinchtab select e8 "value" --snap-diff # select + return only changed elements```---@@ -138,7 +142,7 @@ pinchtab snap # full treepinchtab snap -i # interactive elements only (smaller)pinchtab snap -c # compact format (fewer tokens)pinchtab snap -i -c # both: cheapest snapshot-pinchtab snap -d # diff: only changes since last snap+pinchtab snap -d # diff: only changes since last snap (prefer --snap-diff on actions)pinchtab snap -s main # scoped to CSS selectorpinchtab snap --max-tokens 2000 # token budget cap```diff --git a/tests/e2e/helpers/cli.sh b/tests/e2e/helpers/cli.shindex c7685f76..d285ffb0 100644--- a/tests/e2e/helpers/cli.sh+++ b/tests/e2e/helpers/cli.sh@@ -4,6 +4,11 @@HELPERS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"source "${HELPERS_DIR}/base.sh"+# Clear any stale tab state file to prevent 404 errors when the CLI tries to+# reuse a tab ID that no longer exists in the server.+rm -f "${XDG_STATE_HOME:-$HOME/.local/state}/pinchtab/current-tab" 2>/dev/null || true+rm -f /tmp/pinchtab-current-tab 2>/dev/null || true+E2E_SUMMARY_TITLE="CLI E2E Test Summary"E2E_SUMMARY_FILE="summary.txt"E2E_REF_JSON_VAR="PT_OUT"@@ -194,10 +199,9 @@ assert_config_version_one_of() {return 1}-# Assert PT_OUT is a bare tab ID. When stdout is redirected to a file (as-# in this harness), `pinchtab nav|goto|navigate` auto-switches to-# machine-friendly output: just the tab ID on stdout (no JSON envelope).-# See stdoutIsPipe() in internal/cli/actions/actions_navigate.go.+# Assert PT_OUT is a bare tab ID. `pinchtab nav|goto|navigate` emits just+# the tab ID on stdout by default (no JSON envelope); pass --json to get+# the full response. See Navigate() in internal/cli/actions/actions_navigate.go.assert_tab_id() {local desc="${1:-returns tab ID}"local trimmeddiff --git a/tests/e2e/scenarios/cli/actions-basic.sh b/tests/e2e/scenarios/cli/actions-basic.shindex 459d4608..58229324 100644--- a/tests/e2e/scenarios/cli/actions-basic.sh+++ b/tests/e2e/scenarios/cli/actions-basic.sh@@ -9,7 +9,7 @@ start_test "pinchtab fill <selector> <text>"pt_ok nav "${FIXTURES_URL}/form.html"pt_ok fill "#username" "hello world"-assert_output_contains "filled" "confirms fill action"+assert_output_contains "OK" "confirms fill action"end_test@@ -32,7 +32,8 @@ end_teststart_test "pinchtab hover <ref>"pt_ok nav "${FIXTURES_URL}/buttons.html"-pt_ok snap+# --full gives JSON (the default snap output is now compact text)+pt_ok snap --full# Pick a stable, interactive element ref instead of the first arbitrary ref.REF=$(find_ref_by_name "Increment" "$PT_OUT")@@ -56,39 +57,47 @@ end_teststart_test "pinchtab mouse move/down/up/wheel"pt_ok nav "${FIXTURES_URL}/mouse-events.html"-pt_ok snap --interactive+# --compact=false gives JSON; --interactive keeps the element filter+pt_ok snap --interactive --compact=falseMOUSE_REF=$(find_ref_by_name "Mouse Target" "$PT_OUT")if assert_ref_found "$MOUSE_REF" "mouse target ref"; thenpt_ok mouse move "$MOUSE_REF"- assert_output_contains "moved" "confirms mouse move action"+ assert_output_contains "OK" "confirms mouse move action"pt_ok mouse down --button left- assert_output_contains "down" "confirms mouse down action"+ assert_output_contains "OK" "confirms mouse down action"pt_ok mouse up --button left- assert_output_contains "up" "confirms mouse up action"+ assert_output_contains "OK" "confirms mouse up action"pt_ok mouse wheel 240 --dx 40- assert_output_contains "wheel" "confirms mouse wheel action"+ assert_output_contains "OK" "confirms mouse wheel action"pt_ok eval "window.mouseFixtureState.mousemoveCount"- assert_output_jq '.result >= 1' "mousemove count incremented" "mousemove count did not increment"+ # Terse output is just the number+ if [[ "$PT_OUT" =~ ^[0-9]+$ ]] && [ "$PT_OUT" -ge 1 ]; then+ echo -e " ${GREEN}✓${NC} mousemove count incremented"+ ((ASSERTIONS_PASSED++)) || true+ else+ echo -e " ${RED}✗${NC} mousemove count did not increment"+ ((ASSERTIONS_FAILED++)) || true+ fipt_ok eval "window.mouseFixtureState.mousedownCount"- assert_json_field ".result" "1" "mousedown count is 1"+ assert_output_contains "1" "mousedown count is 1"pt_ok eval "window.mouseFixtureState.mouseupCount"- assert_json_field ".result" "1" "mouseup count is 1"+ assert_output_contains "1" "mouseup count is 1"pt_ok eval "window.mouseFixtureState.lastButton"- assert_json_field ".result" "left" "last button is left"+ assert_output_contains "left" "last button is left"pt_ok eval "window.mouseFixtureState.wheelCount"- assert_json_field ".result" "1" "wheel count is 1"+ assert_output_contains "1" "wheel count is 1"pt_ok eval "window.mouseFixtureState.wheelDeltaY"- assert_json_field ".result" "240" "wheel delta Y accumulated"+ assert_output_contains "240" "wheel delta Y accumulated"fiend_test@@ -97,21 +106,28 @@ end_teststart_test "pinchtab drag <from> <to>"pt_ok nav "${FIXTURES_URL}/mouse-events.html"-pt_ok snap --interactive+pt_ok snap --interactive --compact=falseDRAG_REF=$(find_ref_by_name "Mouse Target" "$PT_OUT")if assert_ref_found "$DRAG_REF" "drag target ref"; thenpt_ok drag "$DRAG_REF" "160,190"- assert_output_contains "up" "confirms drag wrapper completed"+ assert_output_contains "OK" "confirms drag wrapper completed"pt_ok eval "window.mouseFixtureState.mousemoveCount"- assert_output_jq '.result >= 2' "drag performs multiple move events" "drag did not perform multiple move events"+ # Terse output is just the number+ if [[ "$PT_OUT" =~ ^[0-9]+$ ]] && [ "$PT_OUT" -ge 2 ]; then+ echo -e " ${GREEN}✓${NC} drag performs multiple move events"+ ((ASSERTIONS_PASSED++)) || true+ else+ echo -e " ${RED}✗${NC} drag did not perform multiple move events"+ ((ASSERTIONS_FAILED++)) || true+ fipt_ok eval "window.mouseFixtureState.mousedownCount"- assert_json_field ".result" "1" "drag performed one mouse down"+ assert_output_contains "1" "drag performed one mouse down"pt_ok eval "window.mouseFixtureState.mouseupCount"- assert_json_field ".result" "1" "drag performed one mouse up"+ assert_output_contains "1" "drag performed one mouse up"fiend_test@@ -122,16 +138,16 @@ start_test "pinchtab check/uncheck <selector>"pt_ok nav "${FIXTURES_URL}/form.html"pt_ok check "#terms"-assert_json_field ".result.checked" "true" "check marks the checkbox"+assert_output_contains "OK" "check marks the checkbox"pt_ok eval "document.querySelector('#terms').checked"-assert_json_field ".result" "true" "DOM checkbox state is checked"+assert_output_contains "true" "DOM checkbox state is checked"pt_ok uncheck "#terms"-assert_json_field ".result.checked" "false" "uncheck clears the checkbox"+assert_output_contains "OK" "uncheck clears the checkbox"pt_ok eval "document.querySelector('#terms').checked"-assert_json_field ".result" "false" "DOM checkbox state is unchecked"+assert_output_contains "false" "DOM checkbox state is unchecked"end_test@@ -147,16 +163,16 @@ end_teststart_test "pinchtab focus <ref>"pt_ok nav "${FIXTURES_URL}/form.html"-pt_ok snap --interactive+pt_ok snap --interactive --compact=falseUSERNAME_REF=$(find_ref_by_role_and_name "textbox" "Username:" "$PT_OUT")if assert_ref_found "$USERNAME_REF" "username input ref"; thenpt_ok focus "$USERNAME_REF"- assert_output_contains "focused" "confirms focus action"+ assert_output_contains "OK" "confirms focus action"# Verify the element is now focusedpt_ok eval "document.activeElement.id"- assert_json_field ".result" "username" "username input is focused"+ assert_output_contains "username" "username input is focused"fiend_test@@ -167,10 +183,10 @@ start_test "pinchtab focus --css <selector>"pt_ok nav "${FIXTURES_URL}/form.html"pt_ok focus --css "#email"-assert_output_contains "focused" "confirms focus by CSS selector"+assert_output_contains "OK" "confirms focus by CSS selector"# Verify the element is now focusedpt_ok eval "document.activeElement.id"-assert_json_field ".result" "email" "email input is focused"+assert_output_contains "email" "email input is focused"end_testdiff --git a/tests/e2e/scenarios/cli/actions-extended.sh b/tests/e2e/scenarios/cli/actions-extended.shindex 9a5dcfbf..e3c9f105 100644--- a/tests/e2e/scenarios/cli/actions-extended.sh+++ b/tests/e2e/scenarios/cli/actions-extended.sh@@ -8,12 +8,12 @@ source "${GROUP_DIR}/../../helpers/cli.sh"start_test "pinchtab type <ref> <text>"pt_ok nav "${FIXTURES_URL}/form.html"-pt_ok snap --interactive+pt_ok snap --interactive --compact=falseUSERNAME_REF=$(find_ref_by_role_and_name "textbox" "Username:" "$PT_OUT")if assert_ref_found "$USERNAME_REF" "username input ref"; thenpt_ok type "$USERNAME_REF" "typed-via-ref"- assert_output_contains "typed" "confirms text was typed"+ assert_output_contains "OK" "confirms text was typed"fiend_test@@ -22,12 +22,12 @@ end_teststart_test "pinchtab click <ref>"pt_ok nav "${FIXTURES_URL}/buttons.html"-pt_ok snap+pt_ok snap --fullBUTTON_REF=$(find_ref_by_role "button" "$PT_OUT")if assert_ref_found "$BUTTON_REF" "button ref"; thenpt_ok click "$BUTTON_REF"- assert_output_contains "clicked" "confirms click by ref"+ assert_output_contains "OK" "confirms click by ref"fiend_test@@ -53,7 +53,7 @@ end_teststart_test "pinchtab hover (basic)"pt_ok nav "${FIXTURES_URL}/form.html"-pt_ok snap --interactive+pt_ok snap --interactive --compact=falseHOVER_REF=$(find_ref_by_role_and_name "textbox" "Username:" "$PT_OUT")if assert_ref_found "$HOVER_REF" "username input ref"; then@@ -70,13 +70,11 @@ pt_ok click --css "#username"# Hold Shift key downpt_ok keydown Shift-assert_output_contains "keydown" "keydown response"-assert_output_contains "Shift" "keydown key name"+assert_output_contains "OK" "keydown response"# Release Shift keypt_ok keyup Shift-assert_output_contains "keyup" "keyup response"-assert_output_contains "Shift" "keyup key name"+assert_output_contains "OK" "keyup response"end_test@@ -88,7 +86,7 @@ pt_ok click --css "#username"# Use keyboard type to simulate keystrokespt_ok keyboard type "hello123"-assert_output_contains "typed" "keyboard type response"+assert_output_contains "OK" "keyboard type response"# Verify the text was actually typed into the inputpt_ok eval "document.querySelector('#username').value"@@ -104,7 +102,7 @@ pt_ok click --css "#email"# Use keyboard inserttext (paste-like, no key events)pt_ok keyboard inserttext "[email protected]"-assert_output_contains "inserted" "keyboard inserttext response"+assert_output_contains "OK" "keyboard inserttext response"# Verify the text was actually insertedpt_ok eval "document.querySelector('#email').value"@@ -148,17 +146,17 @@ pt_ok click --css "#email"# Type text containing periods (email address)pt_ok keyboard type "[email protected]"-assert_output_contains "typed" "keyboard type response"+assert_output_contains "OK" "keyboard type response"# Verify dots were preservedpt_ok eval "document.querySelector('#email').value"-assert_json_field ".result" "[email protected]" "period characters preserved"+assert_output_contains "[email protected]" "period characters preserved"# Test IP address (multiple dots)pt_ok click --css "#username"pt_ok keyboard type "192.168.1.100"pt_ok eval "document.querySelector('#username').value"-assert_json_field ".result" "192.168.1.100" "multiple dots preserved"+assert_output_contains "192.168.1.100" "multiple dots preserved"end_test@@ -177,7 +175,7 @@ pt_ok click "--css" "#submit-btn"# The JS submit handler must have fired and written LOGIN_SUCCESS to #result.pt_ok eval "document.getElementById('result-success')?.textContent"-assert_json_field ".result" "LOGIN_SUCCESS" "JS submit handler fired on button click"+assert_output_contains "LOGIN_SUCCESS" "JS submit handler fired on button click"end_test@@ -190,7 +188,7 @@ pt_ok fill "#password" "wrong"pt_ok click "--css" "#submit-btn"pt_ok eval "document.getElementById('result-failure')?.textContent"-assert_json_field ".result" "LOGIN_FAILURE" "JS submit handler fired and returned failure"+assert_output_contains "LOGIN_FAILURE" "JS submit handler fired and returned failure"end_test@@ -206,11 +204,11 @@ pt_ok click --css "#username"# Type a long string (65 chars) - should not timeoutLONG_TEXT="The quick brown fox jumps over the lazy dog and keeps on running"pt_ok keyboard type "$LONG_TEXT"-assert_output_contains "typed" "keyboard type response"+assert_output_contains "OK" "keyboard type response"# Verify the text was typed correctlypt_ok eval "document.querySelector('#username').value"-assert_json_field ".result" "$LONG_TEXT" "long string typed correctly"+assert_output_contains "$LONG_TEXT" "long string typed correctly"end_test@@ -220,7 +218,7 @@ start_test "pinchtab wait --not-text (immediate, absent)"# Text that never existed — should succeed immediately.pt_ok nav "${FIXTURES_URL}/buttons.html"pt_ok wait --not-text "nonexistent-text-xyz" --timeout 2000-assert_output_contains "waited" "wait response present"+assert_output_contains "OK" "wait response present"end_test@@ -231,16 +229,134 @@ start_test "pinchtab wait --not-text (after DOM change)"pt_ok nav "${FIXTURES_URL}/buttons.html"pt_ok click --css "#toggle-btn"pt_ok wait --not-text "This content can be toggled." --timeout 5000-assert_output_contains "waited" "wait returned after text disappeared"+assert_output_contains "OK" "wait returned after text disappeared"end_test# ─────────────────────────────────────────────────────────────────start_test "pinchtab wait --not-text (timeout when text persists)"-# Text stays on page — command should return (200) with waited=false.+# Text stays on page — command should timeout (exit code 4).+pt_ok nav "${FIXTURES_URL}/buttons.html"+pt wait --not-text "Increment" --timeout 500+# Expect non-zero exit due to timeout+if [ "$PT_CODE" -ne 0 ]; then+ echo -e " ${GREEN}✓${NC} timeout reported when text persists (exit $PT_CODE)"+ ((ASSERTIONS_PASSED++)) || true+else+ echo -e " ${RED}✗${NC} expected timeout, got success"+ ((ASSERTIONS_FAILED++)) || true+fi++end_test++# ─────────────────────────────────────────────────────────────────+start_test "pinchtab click --snap"+pt_ok nav "${FIXTURES_URL}/buttons.html"-pt_ok wait --not-text "Increment" --timeout 500-assert_output_contains "timeout" "timeout reported when text persists"+pt_ok click --css "#increment" --snap++# Output should contain OK and snapshot content+assert_output_contains "OK" "click succeeded"+assert_output_contains "button" "snapshot contains button element"++end_test++# ─────────────────────────────────────────────────────────────────+start_test "pinchtab nav --snap"++pt_ok nav "${FIXTURES_URL}/form.html" --snap++# Output should contain tab ID and snapshot+assert_output_contains "textbox" "snapshot contains form input"++end_test++# ─────────────────────────────────────────────────────────────────+start_test "pinchtab fill --snap"++pt_ok nav "${FIXTURES_URL}/form.html"+pt_ok fill "#username" "testuser" --snap++# Output should contain OK and snapshot+assert_output_contains "OK" "fill succeeded"+assert_output_contains "textbox" "snapshot contains form input"++end_test++# ─────────────────────────────────────────────────────────────────+start_test "pinchtab select --snap"++pt_ok nav "${FIXTURES_URL}/form.html"+pt_ok select "#country" "us" --snap++# Output should contain OK and snapshot+assert_output_contains "OK" "select succeeded"+assert_output_contains "combobox" "snapshot contains select element"++end_test++# ─────────────────────────────────────────────────────────────────+start_test "pinchtab back --snap"++pt_ok nav "${FIXTURES_URL}/index.html"+pt_ok nav "${FIXTURES_URL}/form.html"+pt_ok back --snap++# Output should contain URL and snapshot+assert_output_contains "index.html" "back navigated to previous URL"+assert_output_contains "link" "snapshot contains navigation elements"++end_test++# ─────────────────────────────────────────────────────────────────+start_test "pinchtab forward --snap"++pt_ok nav "${FIXTURES_URL}/index.html"+pt_ok nav "${FIXTURES_URL}/form.html"+pt_ok back+pt_ok forward --snap++# Output should contain URL and snapshot+assert_output_contains "form.html" "forward navigated to next URL"+assert_output_contains "textbox" "snapshot contains form input"++end_test++# ─────────────────────────────────────────────────────────────────+start_test "pinchtab reload --snap"++pt_ok nav "${FIXTURES_URL}/form.html"+pt_ok reload --snap++# Output should contain OK and snapshot+assert_output_contains "OK" "reload succeeded"+assert_output_contains "textbox" "snapshot contains form input"++end_test++# ─────────────────────────────────────────────────────────────────+start_test "pinchtab click --snap-diff"++pt_ok nav "${FIXTURES_URL}/buttons.html"+pt_ok snap # establish baseline+pt_ok click --css "#increment" --snap-diff++# Output should contain OK and compact diff format (+N ~N -N)+assert_output_contains "OK" "click succeeded"+assert_output_contains "~" "snap-diff shows changes"++end_test++# ─────────────────────────────────────────────────────────────────+start_test "pinchtab fill --snap-diff"++pt_ok nav "${FIXTURES_URL}/form.html"+pt_ok snap # establish baseline+pt_ok fill "#username" "diffuser" --snap-diff++# Output should contain OK and compact diff format (+N ~N -N)+assert_output_contains "OK" "fill succeeded"+assert_output_contains "~" "snap-diff shows changes"end_testdiff --git a/tests/e2e/scenarios/cli/browser-basic.sh b/tests/e2e/scenarios/cli/browser-basic.shindex 64ed9bab..401c96c1 100644--- a/tests/e2e/scenarios/cli/browser-basic.sh+++ b/tests/e2e/scenarios/cli/browser-basic.sh@@ -8,8 +8,8 @@ source "${GROUP_DIR}/../../helpers/cli.sh"start_test "pinchtab health"pt_ok health-assert_output_json-assert_output_contains "status" "returns status field"+# Terse mode outputs "ok" on success+assert_output_contains "ok" "returns ok status"end_test@@ -85,7 +85,8 @@ end_teststart_test "pinchtab snap"pt_ok nav "${FIXTURES_URL}/index.html"-pt_ok snap+# --full gives JSON (the default snap output is now compact text)+pt_ok snap --fullassert_output_jsonassert_output_contains "nodes" "returns snapshot nodes"@@ -135,8 +136,17 @@ start_test "pinchtab text"pt_ok nav "${FIXTURES_URL}/index.html"pt_ok text+# Default output is plain text (no JSON wrapper)+assert_output_contains "Welcome" "returns page text"++end_test++# ─────────────────────────────────────────────────────────────────+start_test "pinchtab text --json"++pt_ok text --jsonassert_output_json-assert_output_contains "text" "returns text field"+assert_output_contains "text" "returns JSON with text field"end_test@@ -145,7 +155,7 @@ start_test "pinchtab text -s <selector>"pt_ok nav "${FIXTURES_URL}/index.html"pt_ok text -s "#welcome"-assert_output_json+# Default output is plain textassert_output_contains "Welcome" "extracts text from element"end_test@@ -154,13 +164,14 @@ end_teststart_test "pinchtab text <ref>"pt_ok nav "${FIXTURES_URL}/index.html"-pt_ok snap -i -c+# -i keeps the interactive filter; --compact=false forces JSON for jq parsing+pt_ok snap -i --compact=false# Extract a ref from the snapshot (first link)REF=$(echo "$PT_OUT" | safe_jq -r '.nodes[] | select(.role == "link") | .ref' | head -1)if [ -n "$REF" ] && [ "$REF" != "null" ]; thenpt_ok text "$REF"- assert_output_json- assert_output_contains "text" "returns text field for ref"+ # Default output is plain text+ assert_output_not_contains "{" "returns plain text, not JSON"elseecho -e " ${YELLOW}⚠${NC} Could not extract ref from snapshot, skipping"fidiff --git a/tests/e2e/scenarios/cli/browser-extended.sh b/tests/e2e/scenarios/cli/browser-extended.shindex 48391867..2dab5028 100644--- a/tests/e2e/scenarios/cli/browser-extended.sh+++ b/tests/e2e/scenarios/cli/browser-extended.sh@@ -10,7 +10,7 @@ start_test "pinchtab scroll <pixels>"pt_ok nav "${FIXTURES_URL}/table.html"pt_ok scroll 100-assert_output_contains "scrolled" "confirms scroll action"+assert_output_contains "OK" "confirms scroll action"end_test@@ -18,10 +18,10 @@ end_teststart_test "pinchtab scroll down/up"pt_ok scroll down-assert_output_contains "scrolled" "scroll down succeeded"+assert_output_contains "OK" "scroll down succeeded"pt_ok scroll up-assert_output_contains "scrolled" "scroll up succeeded"+assert_output_contains "OK" "scroll up succeeded"end_test@@ -118,7 +118,7 @@ start_test "redirects: follow single redirect"pt_ok nav "${FIXTURES_URL}/redirect/1"pt_ok snap-assert_json_field_contains ".url" "fixtures/get" "landed on /get after redirect"+assert_output_contains "fixtures/get" "landed on /get after redirect"end_test@@ -127,7 +127,7 @@ start_test "redirects: follow multiple redirects"pt_ok nav "${FIXTURES_URL}/redirect/3"pt_ok snap-assert_json_field_contains ".url" "fixtures/get" "multiple redirects followed to /get"+assert_output_contains "fixtures/get" "multiple redirects followed to /get"end_test@@ -136,7 +136,8 @@ start_test "pinchtab find (basic)"pt_ok nav "${FIXTURES_URL}/form.html"pt_ok find "username"-assert_output_contains "ref" "has ref in output"+# Output format: e1<tab>textbox<tab>"Username:"+assert_output_contains "e1" "has ref in output"end_testdiff --git a/tests/e2e/scenarios/cli/cache-basic.sh b/tests/e2e/scenarios/cli/cache-basic.shindex 2562f512..2dc197f5 100755--- a/tests/e2e/scenarios/cli/cache-basic.sh+++ b/tests/e2e/scenarios/cli/cache-basic.sh@@ -9,14 +9,14 @@ start_test "pinchtab cache clear"pt_ok nav "${FIXTURES_URL}/form.html"pt_ok cache clear-assert_output_contains "cleared" "cache clear response"+assert_output_contains "OK" "cache clear response"end_test# ─────────────────────────────────────────────────────────────────start_test "pinchtab cache status"-pt_ok cache status+pt_ok cache status --jsonassert_json_field ".canClear" "true" "cache can be cleared"end_test@@ -26,6 +26,6 @@ start_test "pinchtab cache clear is idempotent"pt_ok cache clearpt_ok cache clear-assert_output_contains "cleared" "cache clear works multiple times"+assert_output_contains "OK" "cache clear works multiple times"end_testdiff --git a/tests/e2e/scenarios/cli/stealth-basic.sh b/tests/e2e/scenarios/cli/stealth-basic.shindex 3fa3d9be..9f5bf0f6 100644--- a/tests/e2e/scenarios/cli/stealth-basic.sh+++ b/tests/e2e/scenarios/cli/stealth-basic.sh@@ -19,7 +19,7 @@ end_teststart_test "bot-detect-cli: navigator.webdriver check"pt_ok eval "navigator.webdriver === true"-assert_json_field '.result' 'false' "webdriver !== true"+assert_output_contains "false" "webdriver !== true"end_test@@ -27,7 +27,7 @@ end_teststart_test "bot-detect-cli: no HeadlessChrome in user agent"pt_ok eval "navigator.userAgent.includes('HeadlessChrome')"-assert_json_field '.result' 'false' "UA clean"+assert_output_contains "false" "UA clean"end_test@@ -35,7 +35,7 @@ end_teststart_test "bot-detect-cli: plugins array present"pt_ok eval "navigator.plugins.length > 0"-assert_json_field '.result' 'true' "plugins exist"+assert_output_contains "true" "plugins exist"end_test@@ -43,7 +43,7 @@ end_teststart_test "bot-detect-cli: chrome.runtime exists"pt_ok eval "!!(window.chrome && window.chrome.runtime)"-assert_json_field '.result' 'true' "chrome.runtime"+assert_output_contains "true" "chrome.runtime"end_test@@ -54,17 +54,17 @@ pt_ok nav "${FIXTURES_URL}/stealth-capabilities.html"sleep 1pt_ok eval "window.__stealthCapabilities.webdriverDescriptorNativeLike"-assert_json_field '.result' 'true' "webdriver descriptor stays native-like"+assert_output_contains "true" "webdriver descriptor stays native-like"pt_ok eval "window.__stealthCapabilities.userAgentVersionCoherent"-assert_json_field '.result' 'true' "user agent version remains coherent"+assert_output_contains "true" "user agent version remains coherent"end_test# ─────────────────────────────────────────────────────────────────────────────start_test "stealth-cli: created tab keeps stealth capability contract"-pt_ok tab new+pt_ok tab new --jsonassert_output_json "tab new returns JSON"TAB_ID=$(echo "$PT_OUT" | jq -r '.tabId // empty')@@ -80,10 +80,10 @@ pt_ok nav "${FIXTURES_URL}/stealth-capabilities.html" --tab "$TAB_ID"sleep 1pt_ok eval "window.__stealthCapabilities.webdriverDescriptorNativeLike" --tab "$TAB_ID"-assert_json_field '.result' 'true' "created tab keeps native webdriver descriptor"+assert_output_contains "true" "created tab keeps native webdriver descriptor"pt_ok eval "window.__stealthCapabilities.intlLocaleCoherent" --tab "$TAB_ID"-assert_json_field '.result' 'true' "created tab keeps locale coherence"+assert_output_contains "true" "created tab keeps locale coherence"pt_ok tab close "$TAB_ID"@@ -92,11 +92,15 @@ end_test# ─────────────────────────────────────────────────────────────────────────────start_test "bot-detect-cli: full test suite score"+# Navigate to bot-detect page in a new tab (previous test closed its tab)+pt_ok nav --new-tab "${FIXTURES_URL}/bot-detect.html"+sleep 1+pt_ok eval "JSON.stringify(window.__botDetectScore || {})"-score=$(echo "$PT_OUT" | jq -r '.result // "{}"')+score="$PT_OUT"pt_ok eval "window.__pinchtab_stealth_level || 'light'"-stealth_level=$(echo "$PT_OUT" | jq -r '.result // "light"')+stealth_level="$PT_OUT"crit=$(echo "$score" | jq -r '.critical // 0')total=$(echo "$score" | jq -r '.criticalTotal // 0')diff --git a/tests/e2e/scenarios/cli/storage-basic.sh b/tests/e2e/scenarios/cli/storage-basic.shindex 6119fc56..c82250e1 100644--- a/tests/e2e/scenarios/cli/storage-basic.sh+++ b/tests/e2e/scenarios/cli/storage-basic.sh@@ -64,7 +64,7 @@ end_teststart_test "pinchtab storage get --tab reads storage for specific tab"# Get the actual tab ID from tabs list-pt_cli tabs list+pt_cli tabs list --jsonTAB_ID=""if [ "$PT_CODE" -eq 0 ]; thenTAB_ID=$(echo "$PT_OUT" | safe_jq -r '.tabs[0].id // empty' 2>/dev/null)diff --git a/tests/e2e/scenarios/cli/system-basic.sh b/tests/e2e/scenarios/cli/system-basic.shindex 18398097..b54ceb03 100644--- a/tests/e2e/scenarios/cli/system-basic.sh+++ b/tests/e2e/scenarios/cli/system-basic.sh@@ -7,7 +7,7 @@ source "${GROUP_DIR}/../../helpers/cli.sh"# ─────────────────────────────────────────────────────────────────start_test "pinchtab instance logs"-pt_ok health+pt_ok health --jsonINSTANCE_ID=$(echo "$PT_OUT" | jq -r '.defaultInstance.id // empty')if [ -n "$INSTANCE_ID" ]; then@@ -249,11 +249,11 @@ start_test "pinchtab activity"pt_ok nav "${FIXTURES_URL}/buttons.html"TAB_ID=$(echo "$PT_OUT" | tr -d '[:space:]')-pt_ok snap --tab "$TAB_ID"+pt_ok snap --tab "$TAB_ID" --fullassert_output_json "snapshot output is valid JSON"pt_ok click --tab "$TAB_ID" "#increment"-assert_output_contains "clicked" "click command completed"+assert_output_contains "OK" "click command completed"pt_ok activity --limit 100assert_output_json "activity output is valid JSON"diff --git a/tests/e2e/scenarios/cli/tabs-basic.sh b/tests/e2e/scenarios/cli/tabs-basic.shindex 7ded090c..23eab39d 100644--- a/tests/e2e/scenarios/cli/tabs-basic.sh+++ b/tests/e2e/scenarios/cli/tabs-basic.sh@@ -9,7 +9,7 @@ start_test "pinchtab tab (list)"pt_ok nav "${FIXTURES_URL}/index.html"-pt_ok tab+pt_ok tab --jsonassert_output_jsonassert_output_contains "tabs" "returns tabs array"@@ -31,7 +31,7 @@ end_test# ─────────────────────────────────────────────────────────────────start_test "pinchtab tab new <url>"-pt_ok tab new "${FIXTURES_URL}/buttons.html"+pt_ok tab new "${FIXTURES_URL}/buttons.html" --jsonassert_output_jsonassert_output_contains "tabId" "returns new tab ID"@@ -49,7 +49,7 @@ end_test# ─────────────────────────────────────────────────────────────────start_test "pinchtab tab (list tabs)"-pt_ok tab+pt_ok tab --jsonassert_output_json "output is valid JSON"assert_output_contains "tabs" "output contains tabs array"@@ -60,14 +60,16 @@ start_test "pinchtab tab <id> (focus by tab ID)"pt nav "${FIXTURES_URL}/index.html"-pt tab+# Tab list now outputs terse format: [*]<id>\t<url>\t<title>+pt tab --jsonassert_output_json "tab list is valid JSON"TAB_ID=$(echo "$PT_OUT" | jq -r '.tabs[0].id // empty')if [ -n "$TAB_ID" ] && [ "$TAB_ID" != "null" ]; thenecho -e " ${BLUE}→ focusing on tab ID: ${TAB_ID:0:12}...${NC}"pt_ok tab "$TAB_ID"- assert_output_contains "focused" "output indicates tab is focused"+ # Output is now the tab ID+ assert_output_contains "$TAB_ID" "output contains focused tab ID"elseecho -e " ${YELLOW}⚠${NC} could not extract tab ID, skipping"((ASSERTIONS_PASSED++)) || true@@ -84,7 +86,7 @@ CLOSE_ID=$(echo "$PT_OUT" | tr -d '[:space:]')if [ -n "$CLOSE_ID" ] && [ "$CLOSE_ID" != "null" ]; thenecho -e " ${MUTED}closing tab: ${CLOSE_ID:0:12}...${NC}"pt_ok tab close "$CLOSE_ID"- assert_output_contains "closed" "output confirms tab was closed"+ assert_output_contains "OK" "output confirms tab was closed"elseecho -e " ${YELLOW}⚠${NC} could not get tab ID from navigate, skipping"((ASSERTIONS_PASSED++)) || truediff --git a/tests/e2e/scenarios/cli/tabs-extended.sh b/tests/e2e/scenarios/cli/tabs-extended.shindex 748aa526..b355fcf4 100644--- a/tests/e2e/scenarios/cli/tabs-extended.sh+++ b/tests/e2e/scenarios/cli/tabs-extended.sh@@ -8,9 +8,8 @@ source "${GROUP_DIR}/../../helpers/cli.sh"start_test "pinchtab back (no history)"pt_ok back-assert_output_json "back returns JSON"-assert_output_contains "tabId" "response contains tabId"-assert_output_contains "url" "response contains url"+# Terse mode outputs just the URL (or "OK" if no URL)+assert_output_contains "http" "back returns URL or OK"end_test@@ -23,9 +22,7 @@ TAB_ID=$(echo "$PT_OUT" | tr -d '[:space:]')pt_ok nav "${FIXTURES_URL}/form.html" --tab "$TAB_ID"pt_ok back --tab "$TAB_ID"-assert_output_json "back returns JSON"assert_output_contains "index.html" "back returned to index.html"-assert_output_contains "$TAB_ID" "back response contains correct tabId"end_test@@ -33,9 +30,7 @@ end_teststart_test "pinchtab forward"pt_ok forward --tab "$TAB_ID"-assert_output_json "forward returns JSON"assert_output_contains "form.html" "forward returned to form.html"-assert_output_contains "$TAB_ID" "forward response contains correct tabId"end_test@@ -43,9 +38,8 @@ end_teststart_test "pinchtab reload"pt_ok reload --tab "$TAB_ID"-assert_output_json "reload returns JSON"-assert_output_contains "form.html" "reload kept same page"-assert_output_contains "$TAB_ID" "reload response contains correct tabId"+# Reload outputs "OK" in terse mode, pt_ok already asserts exit 0+assert_output_contains "OK" "reload outputs OK"end_test@@ -101,11 +95,11 @@ start_test "tab eviction: open tabs up to limit"TAB_IDS=()for i in $(seq 1 $MAX_TABS); do- pt_ok nav "${FIXTURES_URL}/index.html?t=$i"+ pt_ok nav --new-tab "${FIXTURES_URL}/index.html?t=$i"TAB_IDS+=($(echo "$PT_OUT" | tr -d '[:space:]'))done-pt_ok tab+pt_ok tab --jsonTAB_COUNT=$(echo "$PT_OUT" | jq '.tabs | length')if [ "$TAB_COUNT" -ge "$MAX_TABS" ]; thenecho -e " ${GREEN}✓${NC} $TAB_COUNT tabs open (>= $MAX_TABS)"@@ -122,7 +116,7 @@ start_test "tab eviction: new tab evicts oldest"FIRST_TAB="${TAB_IDS[0]}"sleep 1-pt_ok nav "${FIXTURES_URL}/index.html?t=overflow"+pt_ok nav --new-tab "${FIXTURES_URL}/index.html?t=overflow"pt_ok tabassert_output_not_contains "$FIRST_TAB" "oldest tab evicted (LRU)"diff --git a/tests/optimization/optimization-loop.md b/tests/optimization/optimization-loop.mdindex 65846381..94a069c0 100644--- a/tests/optimization/optimization-loop.md+++ b/tests/optimization/optimization-loop.md@@ -40,15 +40,13 @@ environment still behaves as expected.Source of truth:-- `scripts/baseline.sh`+- `tests/tools/scripts/baseline.sh`Run baseline directly:```bash-cd tests/benchmark-./scripts/run-optimization.sh-./scripts/baseline.sh-./scripts/finalize-report.sh "$(cat ./results/current_baseline_report.txt)"+# From repo root:+./dev opt baseline```### When to run baselinediff --git a/tests/optimization/results/optimization_log.md b/tests/optimization/results/optimization_log.mdnew file mode 100644index 00000000..9ad4e84c--- /dev/null+++ b/tests/optimization/results/optimization_log.md@@ -0,0 +1,27 @@+# Optimization Log++## 2026-04-20 Entry 1++**Baseline:** baseline_20260420_170428.json (85/85 passed)+**Agent:** pinchtab_benchmark_20260420_185144.json (24/24 passed)++**Gap:** None — agent at 100% on current 6-group benchmark scope.++**Changes made this session:**+1. Fixed `resolveActiveReport()` priority bug — was selecting agent-browser report instead of pinchtab+2. Added "don't run extra commands after step-end" prompt instruction — agent was hallucinating `./scripts/runner report`+3. Added `--snap` and `--snap-diff` flags to scroll command — agent was chaining `scroll && snap`+4. Added better eval error hints for null reference errors+5. Fixed task 2.2 — dropdown task mentioned "File" and "Save" but fixture has "Choose option" and "Alpha/Beta/Gamma"+6. Updated docs: scroll.md, commands.md, benchmark.md, optimization-loop.md++**Why:** These were blocking issues discovered during benchmark runs:+- Report resolution bug caused steps to write to wrong report file+- Agent wasting turns on hallucinated commands+- Agent chaining scroll+snap instead of single command+- Confusing eval errors+- Task/fixture mismatch causing agent confusion++**Result:** 10% token reduction (881k → 792k), 5.5% fewer requests (91 → 86)++**Next focus:** Benchmark expansion — current 6-group scope is saturated (100% pass). Consider adding groups from tests/optimization/ that exercise uncovered scenarios.diff --git a/tests/tools/runner/summary.go b/tests/tools/runner/summary.goindex c809424f..4bc41db5 100644--- a/tests/tools/runner/summary.go+++ b/tests/tools/runner/summary.go@@ -105,8 +105,7 @@ func PrintStartBanner(w io.Writer, lane Lane, benchmarkDir string, groups []int,totalSteps := 0for _, g := range selected {- var steps []groupStep- steps = loadGroupSteps(benchmarkDir, g)+ steps := loadGroupSteps(benchmarkDir, g)_, _ = fmt.Fprintf(w, "\n Group %d — %d step(s):\n", g, len(steps))for _, s := range steps {_, _ = fmt.Fprintf(w, " %d.%d %s\n", s.Group, s.Step, s.Title)