Skip to content

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/.gitignore
index c723c4a0..1eac2124 100644
--- a/.gitignore
+++ b/.gitignore
@@ -52,4 +52,5 @@ pinchtab-small
pinchtab.exe
plugins/*/.venv/
tests/e2e/results/*
-runner
\ No newline at end of file
+runner
+skills/agent-browser
\ No newline at end of file
diff --git a/cmd/pinchtab/cmd_cli_browser_actions.go b/cmd/pinchtab/cmd_cli_browser_actions.go
index 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.go
index 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.go
index 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.go
index a68977be..9aa247b8 100644
--- a/cmd/pinchtab/cmd_cli_register.go
+++ b/cmd/pinchtab/cmd_cli_register.go
@@ -2,6 +2,8 @@ package main
import (
"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.md
index 2fd14fab..71b834c2 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -25,6 +25,7 @@ pinchtab nav <url> --tab <id> # Reuse a specific tab
pinchtab nav <url> --new-tab # Explicitly force a new tab
pinchtab nav <url> --block-images # Block images for this navigation
pinchtab nav <url> --block-ads # Block ads for this navigation
+pinchtab nav <url> --snap # Navigate and output interactive snapshot
pinchtab quick <url> # Navigate and take a snapshot
pinchtab back # Go back in the active tab
pinchtab back --tab <id> # Go back in a specific tab
@@ -73,6 +74,7 @@ pinchtab frame main # Return selector scope to the top docume
pinchtab click [selector] # Click an element or coordinates with --x/--y
pinchtab click --css <selector> # Force CSS selector mode
pinchtab click --wait-nav <selector> # Click and wait for navigation
+pinchtab click --snap <selector> # Click and output interactive snapshot
pinchtab dblclick [selector] # Double-click
pinchtab type <selector> <text> # Type via key events
pinchtab fill <selector> <text> # Fill directly
@@ -86,6 +88,8 @@ pinchtab mouse wheel [dy|selector] # Dispatch wheel deltas
pinchtab drag <from> <to> # Drag between targets (selector/ref or x,y)
pinchtab focus [selector] # Focus an element
pinchtab 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 diff
pinchtab select <selector> <value> # Select a <select> option
pinchtab check <selector> # Check a checkbox or radio
pinchtab uncheck <selector> # Uncheck a checkbox or radio
diff --git a/docs/deep-dive/benchmark.md b/docs/deep-dive/benchmark.md
index 4eb79447..8dfbb1c0 100644
--- a/docs/deep-dive/benchmark.md
+++ b/docs/deep-dive/benchmark.md
@@ -1,14 +1,38 @@
# Benchmark: Deep Dive
This 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 of
agent-browser's extra tokens are `cache_read` at $0.10/1M — cheap per token
but 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 be
treated 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, we
re-ran both lanes against **6 groups (0, 1, 2, 3, 4, 5)** — 24 steps per
run — 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 later
groups contain structurally harder steps — dashboards with dynamic
@@ -255,21 +252,90 @@ Two things move:
**agent-browser variance is larger at extended scope.** lae3 (160
requests, $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.
### Takeaway
The 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-noise
apples-to-apples anchor (tight groups, high replicate count), and cite
the 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 with
arguments, 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-run
variance remains ~25–30% of mean; agent-browser has one outlier in
each 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 across
lanes, but absolute times are not production-representative
- Score is pass-count, not answer quality or time-to-complete
diff --git a/docs/reference/scroll.md b/docs/reference/scroll.md
index 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 Alternative
pinchtab 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 down
Notes:
+- 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.go
index 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.go
index 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 := 0
for i, n := range nodes {
diff --git a/internal/bridge/observe_facade.go b/internal/bridge/observe_facade.go
index 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.A11yNode
type 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.go
index 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.go
index 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]any
if 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.go
index aaec7364..36aaf09c 100644
--- a/internal/cli/actions/actions_dialog.go
+++ b/internal/cli/actions/actions_dialog.go
@@ -1,21 +1,31 @@
package actions
import (
- "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.go
index 69b71c47..c8ebc266 100644
--- a/internal/cli/actions/actions_element.go
+++ b/internal/cli/actions/actions_element.go
@@ -1,7 +1,7 @@
package actions
import (
- "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.C
tabID, _ := 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.go
index 16539fce..4269f38d 100644
--- a/internal/cli/actions/actions_evaluate.go
+++ b/internal/cli/actions/actions_evaluate.go
@@ -1,11 +1,13 @@
package actions
import (
+ "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 *cobra
tabID, _ := 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.go
index 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.Comm
threshold, _ := 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.Comm
path := "/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 ref
if 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.go
index 86dcaa92..2726e6e3 100644
--- a/internal/cli/actions/actions_navigate.go
+++ b/internal/cli/actions/actions_navigate.go
@@ -2,31 +2,43 @@ package actions
import (
"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.go
index 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.go
index c08e4357..be65fa09 100644
--- a/internal/cli/actions/actions_system.go
+++ b/internal/cli/actions/actions_system.go
@@ -3,16 +3,42 @@ package actions
import (
"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.go
index 874908dc..9bd3854f 100644
--- a/internal/cli/actions/actions_system_test.go
+++ b/internal/cli/actions/actions_system_test.go
@@ -2,15 +2,24 @@ package actions
import (
"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.go
index 1aa8b062..0c37b417 100644
--- a/internal/cli/actions/actions_tabs.go
+++ b/internal/cli/actions/actions_tabs.go
@@ -1,21 +1,47 @@
package actions
import (
+ "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 running
instances := 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.go
index d2f51dac..8369a722 100644
--- a/internal/cli/actions/actions_text.go
+++ b/internal/cli/actions/actions_text.go
@@ -1,10 +1,12 @@
package actions
import (
+ "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.go
index 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.go
index 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.Com
path := "/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.go
index 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.go
new file mode 100644
index 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.go
index 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.go
index 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.go
index c52a7702..2621c2b0 100644
--- a/internal/mcp/handlers_interaction.go
+++ b/internal/mcp/handlers_interaction.go
@@ -3,6 +3,7 @@ package mcp
import (
"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.CallToolRequ
if 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.go
index 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.go
index 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.md
index 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.
## References
diff --git a/skills/pinchtab/references/agent-optimization.md b/skills/pinchtab/references/agent-optimization.md
index 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.md
index 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`).
```bash
pinchtab click e5
+pinchtab click e5 --snap-diff # click + return only changed elements
+pinchtab click e5 --snap # click + return full snapshot
pinchtab click e5 --tab <tabId>
```
@@ -79,6 +81,7 @@ Fill a form field using JS event dispatch. Prefer over `type` for React/Vue/Angu
```bash
pinchtab 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.
```bash
pinchtab select e8 "option-value"
+pinchtab select e8 "value" --snap-diff # select + return only changed elements
```
---
@@ -138,7 +142,7 @@ pinchtab snap # full tree
pinchtab 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 selector
pinchtab snap --max-tokens 2000 # token budget cap
```
diff --git a/tests/e2e/helpers/cli.sh b/tests/e2e/helpers/cli.sh
index 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 trimmed
diff --git a/tests/e2e/scenarios/cli/actions-basic.sh b/tests/e2e/scenarios/cli/actions-basic.sh
index 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_test
start_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_test
start_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=false
MOUSE_REF=$(find_ref_by_name "Mouse Target" "$PT_OUT")
if assert_ref_found "$MOUSE_REF" "mouse target ref"; then
pt_ok mouse move "$MOUSE_REF"
- assert_output_contains "moved" "confirms mouse move action"
+ 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
+ fi
pt_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"
fi
end_test
@@ -97,21 +106,28 @@ end_test
start_test "pinchtab drag <from> <to>"
pt_ok nav "${FIXTURES_URL}/mouse-events.html"
-pt_ok snap --interactive
+pt_ok snap --interactive --compact=false
DRAG_REF=$(find_ref_by_name "Mouse Target" "$PT_OUT")
if assert_ref_found "$DRAG_REF" "drag target ref"; then
pt_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
+ fi
pt_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"
fi
end_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_test
start_test "pinchtab focus <ref>"
pt_ok nav "${FIXTURES_URL}/form.html"
-pt_ok snap --interactive
+pt_ok snap --interactive --compact=false
USERNAME_REF=$(find_ref_by_role_and_name "textbox" "Username:" "$PT_OUT")
if assert_ref_found "$USERNAME_REF" "username input ref"; then
pt_ok focus "$USERNAME_REF"
- assert_output_contains "focused" "confirms focus action"
+ assert_output_contains "OK" "confirms focus action"
# Verify the element is now focused
pt_ok eval "document.activeElement.id"
- assert_json_field ".result" "username" "username input is focused"
+ assert_output_contains "username" "username input is focused"
fi
end_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 focused
pt_ok eval "document.activeElement.id"
-assert_json_field ".result" "email" "email input is focused"
+assert_output_contains "email" "email input is focused"
end_test
diff --git a/tests/e2e/scenarios/cli/actions-extended.sh b/tests/e2e/scenarios/cli/actions-extended.sh
index 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=false
USERNAME_REF=$(find_ref_by_role_and_name "textbox" "Username:" "$PT_OUT")
if assert_ref_found "$USERNAME_REF" "username input ref"; then
pt_ok type "$USERNAME_REF" "typed-via-ref"
- assert_output_contains "typed" "confirms text was typed"
+ assert_output_contains "OK" "confirms text was typed"
fi
end_test
@@ -22,12 +22,12 @@ end_test
start_test "pinchtab click <ref>"
pt_ok nav "${FIXTURES_URL}/buttons.html"
-pt_ok snap
+pt_ok snap --full
BUTTON_REF=$(find_ref_by_role "button" "$PT_OUT")
if assert_ref_found "$BUTTON_REF" "button ref"; then
pt_ok click "$BUTTON_REF"
- assert_output_contains "clicked" "confirms click by ref"
+ assert_output_contains "OK" "confirms click by ref"
fi
end_test
@@ -53,7 +53,7 @@ end_test
start_test "pinchtab hover (basic)"
pt_ok nav "${FIXTURES_URL}/form.html"
-pt_ok snap --interactive
+pt_ok snap --interactive --compact=false
HOVER_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 down
pt_ok keydown Shift
-assert_output_contains "keydown" "keydown response"
-assert_output_contains "Shift" "keydown key name"
+assert_output_contains "OK" "keydown response"
# Release Shift key
pt_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 keystrokes
pt_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 input
pt_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 inserted
pt_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 preserved
pt_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 timeout
LONG_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 correctly
pt_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_test
diff --git a/tests/e2e/scenarios/cli/browser-basic.sh b/tests/e2e/scenarios/cli/browser-basic.sh
index 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_test
start_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 --full
assert_output_json
assert_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 --json
assert_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 text
assert_output_contains "Welcome" "extracts text from element"
end_test
@@ -154,13 +164,14 @@ end_test
start_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" ]; then
pt_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"
else
echo -e " ${YELLOW}⚠${NC} Could not extract ref from snapshot, skipping"
fi
diff --git a/tests/e2e/scenarios/cli/browser-extended.sh b/tests/e2e/scenarios/cli/browser-extended.sh
index 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_test
start_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_test
diff --git a/tests/e2e/scenarios/cli/cache-basic.sh b/tests/e2e/scenarios/cli/cache-basic.sh
index 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 --json
assert_json_field ".canClear" "true" "cache can be cleared"
end_test
@@ -26,6 +26,6 @@ start_test "pinchtab cache clear is idempotent"
pt_ok cache clear
pt_ok cache clear
-assert_output_contains "cleared" "cache clear works multiple times"
+assert_output_contains "OK" "cache clear works multiple times"
end_test
diff --git a/tests/e2e/scenarios/cli/stealth-basic.sh b/tests/e2e/scenarios/cli/stealth-basic.sh
index 3fa3d9be..9f5bf0f6 100644
--- a/tests/e2e/scenarios/cli/stealth-basic.sh
+++ b/tests/e2e/scenarios/cli/stealth-basic.sh
@@ -19,7 +19,7 @@ end_test
start_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_test
start_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_test
start_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_test
start_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 1
pt_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 --json
assert_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 1
pt_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.sh
index 6119fc56..c82250e1 100644
--- a/tests/e2e/scenarios/cli/storage-basic.sh
+++ b/tests/e2e/scenarios/cli/storage-basic.sh
@@ -64,7 +64,7 @@ end_test
start_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 --json
TAB_ID=""
if [ "$PT_CODE" -eq 0 ]; then
TAB_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.sh
index 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 --json
INSTANCE_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" --full
assert_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 100
assert_output_json "activity output is valid JSON"
diff --git a/tests/e2e/scenarios/cli/tabs-basic.sh b/tests/e2e/scenarios/cli/tabs-basic.sh
index 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 --json
assert_output_json
assert_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" --json
assert_output_json
assert_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 --json
assert_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 --json
assert_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" ]; then
echo -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"
else
echo -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" ]; then
echo -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"
else
echo -e " ${YELLOW}⚠${NC} could not get tab ID from navigate, skipping"
((ASSERTIONS_PASSED++)) || true
diff --git a/tests/e2e/scenarios/cli/tabs-extended.sh b/tests/e2e/scenarios/cli/tabs-extended.sh
index 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_test
start_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_test
start_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 --json
TAB_COUNT=$(echo "$PT_OUT" | jq '.tabs | length')
if [ "$TAB_COUNT" -ge "$MAX_TABS" ]; then
echo -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 tab
assert_output_not_contains "$FIRST_TAB" "oldest tab evicted (LRU)"
diff --git a/tests/optimization/optimization-loop.md b/tests/optimization/optimization-loop.md
index 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 baseline
diff --git a/tests/optimization/results/optimization_log.md b/tests/optimization/results/optimization_log.md
new file mode 100644
index 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.go
index 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 := 0
for _, 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)