Skip to content

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

perf(snapshot): default the agent-facing snapshot to compact and skip enrichment the format cannot carry

Luigi Agosti40cdbac4ba45
diff --git a/cmd/pinchtab/cmd_cli_register.go b/cmd/pinchtab/cmd_cli_register.go
index 1a4ed0d8..e61810a3 100644
--- a/cmd/pinchtab/cmd_cli_register.go
+++ b/cmd/pinchtab/cmd_cli_register.go
@@ -107,7 +107,8 @@ func configureBrowserFlags() {
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("full", false, "Full JSON output (shorthand for --interactive=false --json)")
+ snapCmd.Flags().Bool("json", false, "JSON output, keeping the interactive filter (same as --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")
diff --git a/cmd/pinchtab/cmd_cli_snap_format_test.go b/cmd/pinchtab/cmd_cli_snap_format_test.go
new file mode 100644
index 00000000..ede7853f
--- /dev/null
+++ b/cmd/pinchtab/cmd_cli_snap_format_test.go
@@ -0,0 +1,74 @@
+package main
+
+import (
+ "io"
+ "net/http"
+ "net/http/httptest"
+ "net/url"
+ "strconv"
+ "testing"
+
+ "github.com/pinchtab/pinchtab/internal/handlers"
+)
+
+func snapWireFormat(t *testing.T, flags map[string]string) url.Values {
+ t.Helper()
+ var query url.Values
+ ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.URL.Path != "/snapshot" {
+ http.NotFound(w, r)
+ return
+ }
+ query = r.URL.Query()
+ _, _ = io.WriteString(w, "# snapshot\n")
+ }))
+ t.Cleanup(ts.Close)
+
+ oldServerURL := serverURL
+ serverURL = ts.URL
+ t.Cleanup(func() { serverURL = oldServerURL })
+
+ snapFlags := snapCmd.Flags()
+ for flag, value := range flags {
+ old, err := snapFlags.GetBool(flag)
+ if err != nil {
+ t.Fatalf("snap has no --%s flag: %v", flag, err)
+ }
+ t.Cleanup(func() { _ = snapFlags.Set(flag, strconv.FormatBool(old)) })
+ if err := snapFlags.Set(flag, value); err != nil {
+ t.Fatalf("cannot set --%s: %v", flag, err)
+ }
+ }
+
+ _ = captureStdout(t, func() {
+ snapCmd.Run(snapCmd, nil)
+ })
+ if query == nil {
+ t.Fatal("snap never reached /snapshot, so this proves nothing about what it asks for")
+ }
+ return query
+}
+
+func TestSnapAsksForCompactWithNoFormatFlag(t *testing.T) {
+ for _, tc := range []struct {
+ name string
+ flags map[string]string
+ want string
+ }{
+ {name: "no flags", flags: nil, want: "compact"},
+ {name: "json", flags: map[string]string{"json": "true"}, want: "json"},
+ {name: "compact declined", flags: map[string]string{"compact": "false"}, want: "json"},
+ {name: "full", flags: map[string]string{"full": "true"}, want: "json"},
+ {name: "text", flags: map[string]string{"text": "true"}, want: "text"},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ query := snapWireFormat(t, tc.flags)
+ if got := query.Get("format"); got != tc.want {
+ t.Errorf("snap asked for format=%q, want %q — read from the real command's own flags, so a default that drifts in registration shows up here", got, tc.want)
+ }
+ if _, err := handlers.ParseSnapshotCostControls(query); err != nil {
+ t.Errorf("the server rejects the query snap sends: %v (query=%v)", err, query)
+ }
+ })
+ }
+}
diff --git a/docs/reference/mcp-tools.md b/docs/reference/mcp-tools.md
index a13fb9f4..ace09d84 100644
--- a/docs/reference/mcp-tools.md
+++ b/docs/reference/mcp-tools.md
@@ -26,7 +26,7 @@ Structured semantic locators are matched by the semantic engine; CSS, XPath, ref
| Tool | Key Parameters | Notes |
| --- | --- | --- |
| `pinchtab_navigate` | `url` required, `tabId`, `snap` | Uses `/navigate`; omitting `tabId` opens a new tab. `snap=true` returns an interactive compact snapshot in the same response |
-| `pinchtab_snapshot` | `tabId`, `interactive`, `compact`, `format`, `diff`, `selector`, `maxTokens`, `depth`, `noAnimations` | `selector` scopes the snapshot; `format` is limited to `compact` or `text` |
+| `pinchtab_snapshot` | `tabId`, `interactive`, `compact`, `format`, `diff`, `selector`, `maxTokens`, `depth`, `noAnimations` | Returns compact by default — the tool asks `/snapshot` for `format=compact` unless `format` says otherwise or `compact=false` asks for the JSON tree. `selector` scopes the snapshot; `format` is limited to `compact` or `text` |
| `pinchtab_frame` | `tabId`, `target` | Get or set the frame scope for selector-based actions on the tab; `target` accepts `main`, a snapshot ref, an iframe selector, or a frame name/URL |
| `pinchtab_screenshot` | `tabId`, `selector`, `scale`, `format`, `quality`, `annotate`, `beyondViewport`, `browser` | `selector` captures a specific element in current frame scope; `scale` rescales the output bitmap (e.g. `0.5` = half size); `format` is `jpeg` or `png`; `annotate=true` overlays numbered ref boxes and populates the annotations envelope; `beyondViewport=true` captures the full scrollable document (ignored when `selector` is set) — box coords are document-relative in that mode; `browser` selects the browser (e.g. `chrome`, `cloak`) for this request |
| `pinchtab_capture` | `tabId`, `selector`, `filter`, `format`, `quality`, `depth`, `scale`, `wait`, `withBounds`, `beyondViewport`, `requirePair`, `noAnimations`, `browser` | Paired screenshot + accessibility snapshot from the same DOM epoch. Returns an image content block plus a JSON envelope with `epoch`, `pairing.navigated`, per-node `boundingBox`, and `image.coordinateSpace` (`viewport`, `document`, or selector `clip`). `browser` selects the browser (e.g. `chrome`, `cloak`); the static ghost-chrome runtime cannot paint, so it falls back to chrome. Use when the model reads pixels AND acts on refs in the same turn. |
diff --git a/docs/reference/snapshot.md b/docs/reference/snapshot.md
index e7efdab2..c5a1c910 100644
--- a/docs/reference/snapshot.md
+++ b/docs/reference/snapshot.md
@@ -47,12 +47,34 @@ pinchtab snap --max-tokens 2000 # Limit output size
| Parameter | Description |
|-----------|-------------|
| `filter` | `interactive` for interactive + headings |
-| `format` | `compact`, `text`, `yaml`, or default JSON |
+| `format` | `compact`, `text`, `yaml`, or default JSON. The CLI and the MCP tool both ask for `compact`; the HTTP default is unchanged |
| `diff` | `true` for diff mode |
| `selector` | CSS selector to scope |
| `maxTokens` | Token budget limit |
| `depth` | Tree depth limit |
+## What a format costs, and what it carries
+
+The same 40 realistic interactive nodes, rendered through each output path:
+
+```
+ compact 1644 bytes ~ 411 tokens 1.0x
+ text 2060 bytes ~ 515 tokens 1.3x
+ json 8211 bytes ~2052 tokens 5.0x
+ yaml 17467 bytes ~4366 tokens 10.6x
+```
+
+55% of that JSON body is the DOM-derived descriptor fields — `tag`, `label`, `placeholder`,
+`alt`, `title`, `testid`, `text` — which exist to feed the server-side semantic matcher.
+`compact` and `text` render `ref`, `role`, `name`, `value` and the state flags and nothing
+else, so those fields cannot appear there at all. The DOM pass that fills them is therefore
+skipped for `compact` and `text`, which also drops one CDP round trip per node from the
+cheapest path.
+
+Skipping it changes nothing the caller can see: the fields are absent from those formats
+either way, and `find` and the semantic selectors enrich the cached nodes themselves before
+matching, so a `compact` snapshot leaves them exactly as capable as a JSON one.
+
## What `maxTokens` guarantees
`maxTokens` is a ceiling, not a hint. The nodes returned are the longest prefix whose
diff --git a/internal/bridge/bridge.go b/internal/bridge/bridge.go
index 68202b61..25ab9495 100644
--- a/internal/bridge/bridge.go
+++ b/internal/bridge/bridge.go
@@ -432,7 +432,9 @@ func (b *Bridge) Snapshot(ctx context.Context, tabID string, filter string, para
maxDepth = -1
}
nodes, refs := BuildSnapshot(rawNodes, filter, maxDepth)
- _ = EnrichA11yNodesWithDOMMetadata(ctx, nodes)
+ if !params.SkipMetadata {
+ _ = EnrichA11yNodesWithDOMMetadata(ctx, nodes)
+ }
targets := RefTargetsFromNodes(nodes)
var url string
diff --git a/internal/bridge/bridge_types.go b/internal/bridge/bridge_types.go
index ad757736..69a7dde2 100644
--- a/internal/bridge/bridge_types.go
+++ b/internal/bridge/bridge_types.go
@@ -322,4 +322,5 @@ func (e *StaticEscalateError) Error() string {
type ContentParams struct {
ContentGuard *contentguard.Scanner
MaxDepth int // max AX tree depth for snapshots; 0 or -1 means unlimited
+ SkipMetadata bool
}
diff --git a/internal/bridge/observe/snapshot.go b/internal/bridge/observe/snapshot.go
index 3f706668..9d669387 100644
--- a/internal/bridge/observe/snapshot.go
+++ b/internal/bridge/observe/snapshot.go
@@ -18,6 +18,21 @@ import (
// value here", nothing more — an empty sensitive field carries no value at all.
const MaskedValue = "••••••••"
+const maskRune = '\u2022'
+
+func normalizeMaskedValue(v string) string {
+ trimmed := strings.TrimSpace(v)
+ if trimmed == "" {
+ return v
+ }
+ for _, r := range trimmed {
+ if r != maskRune {
+ return v
+ }
+ }
+ return MaskedValue
+}
+
// IsSensitiveAutocomplete reports whether an autocomplete token marks a field
// whose content must never be printed.
func IsSensitiveAutocomplete(value string) bool {
@@ -478,7 +493,7 @@ func BuildSnapshot(nodes []RawAXNode, filter string, maxDepth int) ([]A11yNode,
}
if v := n.Value.String(); v != "" {
- entry.Value = v
+ entry.Value = normalizeMaskedValue(v)
}
if n.BackendDOMNodeID != 0 {
entry.NodeID = n.BackendDOMNodeID
diff --git a/internal/bridge/password_mask_browser_test.go b/internal/bridge/password_mask_browser_test.go
index cc7f4e79..ac382a52 100644
--- a/internal/bridge/password_mask_browser_test.go
+++ b/internal/bridge/password_mask_browser_test.go
@@ -3,6 +3,7 @@ package bridge
import (
"context"
"encoding/base64"
+ "strings"
"testing"
"time"
@@ -84,3 +85,62 @@ func TestSnapshotDistinguishesEmptyAndFilledPasswordInRealBrowser(t *testing.T)
}
}
}
+
+func TestAnUnenrichedSnapshotStillKeepsAPasswordOut(t *testing.T) {
+ chromePath := testbrowser.Path(t)
+
+ alloc, cancelAlloc := chromedp.NewExecAllocator(context.Background(), append(
+ chromedp.DefaultExecAllocatorOptions[:],
+ chromedp.ExecPath(chromePath),
+ chromedp.UserDataDir(testbrowser.ProfileDir(t)),
+ chromedp.Flag("headless", true),
+ chromedp.Flag("no-sandbox", true),
+ )...)
+ ctx, cancelBrowser := chromedp.NewContext(alloc)
+ ctx, cancelTimeout := context.WithTimeout(ctx, 30*time.Second)
+ t.Cleanup(func() {
+ cancelTimeout()
+ cancelBrowser()
+ cancelAlloc()
+ })
+
+ const secret = "supersecret123"
+ html := `<form>
+ <label for="offAutocomplete">Password</label>
+ <input id="offAutocomplete" type="password" autocomplete="off">
+ <label for="current">Current password</label>
+ <input id="current" type="password" autocomplete="current-password">
+ <button type="submit">Continue</button>
+ </form>`
+ if err := chromedp.Run(ctx,
+ chromedp.Navigate("data:text/html;base64,"+base64.StdEncoding.EncodeToString([]byte(html))),
+ chromedp.SendKeys("#offAutocomplete", secret, chromedp.ByID),
+ chromedp.SendKeys("#current", secret, chromedp.ByID),
+ ); err != nil {
+ t.Fatal(err)
+ }
+
+ rawNodes, err := FetchAXTree(ctx)
+ if err != nil {
+ t.Fatal(err)
+ }
+ flat, _ := BuildSnapshot(rawNodes, "", -1)
+
+ textboxes := 0
+ for i := range flat {
+ if strings.Contains(flat[i].Value, secret) || strings.Contains(flat[i].Text, secret) {
+ t.Errorf("a snapshot built without DOM enrichment carries the password: %+v", flat[i])
+ }
+ if flat[i].Role != "textbox" {
+ continue
+ }
+ textboxes++
+ if flat[i].Value != bridgeobserve.MaskedValue {
+ t.Errorf("filled password field value = %q, want %q — the accessibility tree reports one bullet per character, so passing it through leaks the secret's length to whoever reads the snapshot",
+ flat[i].Value, bridgeobserve.MaskedValue)
+ }
+ }
+ if textboxes < 2 {
+ t.Fatalf("expected both password fields in the snapshot, found %d textboxes in %+v", textboxes, flat)
+ }
+}
diff --git a/internal/bridge/snapshot_metadata_browser_test.go b/internal/bridge/snapshot_metadata_browser_test.go
new file mode 100644
index 00000000..c67770cf
--- /dev/null
+++ b/internal/bridge/snapshot_metadata_browser_test.go
@@ -0,0 +1,80 @@
+package bridge
+
+import (
+ "context"
+ "encoding/base64"
+ "testing"
+ "time"
+
+ "github.com/chromedp/chromedp"
+ "github.com/pinchtab/pinchtab/internal/config"
+ "github.com/pinchtab/pinchtab/internal/testbrowser"
+)
+
+func newMetadataBridge(t *testing.T) (*Bridge, context.Context) {
+ t.Helper()
+ chromePath := testbrowser.Path(t)
+
+ alloc, cancelAlloc := chromedp.NewExecAllocator(context.Background(), append(
+ chromedp.DefaultExecAllocatorOptions[:],
+ chromedp.ExecPath(chromePath),
+ chromedp.UserDataDir(testbrowser.ProfileDir(t)),
+ chromedp.Flag("headless", true),
+ chromedp.Flag("no-sandbox", true),
+ )...)
+ ctx, cancelBrowser := chromedp.NewContext(alloc)
+ ctx, cancelTimeout := context.WithTimeout(ctx, 30*time.Second)
+ t.Cleanup(func() {
+ cancelTimeout()
+ cancelBrowser()
+ cancelAlloc()
+ })
+
+ html := `<form><label for="email">Email</label>
+ <input id="email" type="text" placeholder="[email protected]" data-testid="signup-email">
+ <button type="submit">Continue</button></form>`
+ if err := chromedp.Run(ctx,
+ chromedp.Navigate("data:text/html;base64,"+base64.StdEncoding.EncodeToString([]byte(html))),
+ chromedp.WaitVisible("#email", chromedp.ByID),
+ ); err != nil {
+ t.Fatal(err)
+ }
+
+ b := New(context.Background(), ctx, &config.RuntimeConfig{})
+ b.RegisterTab("tab-metadata", ctx)
+ return b, ctx
+}
+
+func TestSnapshotSkipsTheDOMPassOnlyWhenAskedTo(t *testing.T) {
+ b, ctx := newMetadataBridge(t)
+
+ for _, tc := range []struct {
+ name string
+ skip bool
+ wantEnriched bool
+ }{
+ {name: "metadata wanted", skip: false, wantEnriched: true},
+ {name: "metadata skipped", skip: true, wantEnriched: false},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ result, err := b.Snapshot(ctx, "tab-metadata", "", ContentParams{SkipMetadata: tc.skip})
+ if err != nil {
+ t.Fatal(err)
+ }
+ if len(result.Nodes) == 0 {
+ t.Fatal("the snapshot is empty, so neither answer here means anything")
+ }
+ enriched := false
+ for _, node := range result.Nodes {
+ if node.Tag != "" || node.TestID != "" || node.Placeholder != "" {
+ enriched = true
+ break
+ }
+ }
+ if enriched != tc.wantEnriched {
+ t.Errorf("SkipMetadata=%v produced enriched=%v, want %v; the flag is what keeps a per-node DOM round trip off the format that cannot render its result",
+ tc.skip, enriched, tc.wantEnriched)
+ }
+ })
+ }
+}
diff --git a/internal/cli/actions/actions_snapshot.go b/internal/cli/actions/actions_snapshot.go
index b6c899c0..12cd89f9 100644
--- a/internal/cli/actions/actions_snapshot.go
+++ b/internal/cli/actions/actions_snapshot.go
@@ -15,13 +15,8 @@ func Snapshot(client *http.Client, base, token string, cmd *cobra.Command, selec
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")
}
+ params.Set("format", snapshotFormat(cmd))
if v, _ := cmd.Flags().GetBool("diff"); v {
params.Set("diff", "true")
}
@@ -42,3 +37,19 @@ func Snapshot(client *http.Client, base, token string, cmd *cobra.Command, selec
result := apiclient.DoGetCapturingVocab(client, base, token, "/snapshot", params, params.Get("tabId"))
apiclient.SuggestNextAction("snapshot", result)
}
+
+func snapshotFormat(cmd *cobra.Command) string {
+ if v, _ := cmd.Flags().GetBool("text"); v {
+ return "text"
+ }
+ if v, _ := cmd.Flags().GetBool("json"); v {
+ return "json"
+ }
+ if v, _ := cmd.Flags().GetBool("full"); v {
+ return "json"
+ }
+ if v, _ := cmd.Flags().GetBool("compact"); v {
+ return "compact"
+ }
+ return "json"
+}
diff --git a/internal/cli/actions/actions_snapshot_test.go b/internal/cli/actions/actions_snapshot_test.go
index 45b83d1b..c955cc1a 100644
--- a/internal/cli/actions/actions_snapshot_test.go
+++ b/internal/cli/actions/actions_snapshot_test.go
@@ -1,16 +1,20 @@
package actions
import (
+ "net/url"
"strings"
"testing"
+ "github.com/pinchtab/pinchtab/internal/handlers"
"github.com/spf13/cobra"
)
func newSnapshotCmd() *cobra.Command {
cmd := &cobra.Command{}
- cmd.Flags().Bool("interactive", false, "")
- cmd.Flags().Bool("compact", false, "")
+ cmd.Flags().Bool("interactive", true, "")
+ cmd.Flags().Bool("compact", true, "")
+ cmd.Flags().Bool("json", false, "")
+ cmd.Flags().Bool("full", false, "")
cmd.Flags().Bool("text", false, "")
cmd.Flags().Bool("diff", false, "")
cmd.Flags().String("selector", "", "")
@@ -20,6 +24,45 @@ func newSnapshotCmd() *cobra.Command {
return cmd
}
+func TestSnapshotFormatFollowsTheFlagsInOnePlace(t *testing.T) {
+ for _, tc := range []struct {
+ name string
+ flags map[string]string
+ want string
+ }{
+ {name: "no flags at all", flags: nil, want: "compact"},
+ {name: "compact declined", flags: map[string]string{"compact": "false"}, want: "json"},
+ {name: "json asked for", flags: map[string]string{"json": "true"}, want: "json"},
+ {name: "full", flags: map[string]string{"full": "true"}, want: "json"},
+ {name: "text", flags: map[string]string{"text": "true"}, want: "text"},
+ {name: "text beats json", flags: map[string]string{"text": "true", "json": "true"}, want: "text"},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ m := newMockServer()
+ defer m.close()
+
+ cmd := newSnapshotCmd()
+ for flag, value := range tc.flags {
+ if err := cmd.Flags().Set(flag, value); err != nil {
+ t.Fatalf("cannot set --%s: %v", flag, err)
+ }
+ }
+ Snapshot(m.server.Client(), m.base(), "", cmd, "")
+
+ query, err := url.ParseQuery(m.lastQuery)
+ if err != nil {
+ t.Fatalf("unreadable query %q: %v", m.lastQuery, err)
+ }
+ if got := query.Get("format"); got != tc.want {
+ t.Errorf("snap asked for format=%q, want %q; the flags decide the cost of the answer, so the wire is what has to say so", got, tc.want)
+ }
+ if _, err := handlers.ParseSnapshotCostControls(query); err != nil {
+ t.Errorf("the server rejects the query snap sends: %v (query=%v)", err, query)
+ }
+ })
+ }
+}
+
func TestSnapshot(t *testing.T) {
m := newMockServer()
m.response = `[{"ref":"e0","role":"button","name":"Submit"}]`
diff --git a/internal/handlers/snapshot.go b/internal/handlers/snapshot.go
index 4529c6e7..c1d15f62 100644
--- a/internal/handlers/snapshot.go
+++ b/internal/handlers/snapshot.go
@@ -75,6 +75,10 @@ func writeIgnoredParamsComment(w http.ResponseWriter, ignored []string) {
}
}
+func snapshotFormatCarriesMetadata(format string) bool {
+ return format == "json" || format == "yaml"
+}
+
func (h *Handlers) HandleSnapshot(w http.ResponseWriter, r *http.Request) {
controls, err := ParseSnapshotCostControls(r.URL.Query())
if err != nil {
@@ -101,6 +105,7 @@ func (h *Handlers) HandleSnapshot(w http.ResponseWriter, r *http.Request) {
reqNoAnim := r.URL.Query().Get("noAnimations") == "true"
maxDepth := controls.MaxDepth
maxTokens := controls.MaxTokens
+ wireCarriesMetadata := snapshotFormatCarriesMetadata(format)
resolvedTabID, tCtx, cancel, ok := h.resolveReadContext(w, r, tabID, effectiveCfg.ActionTimeout)
if !ok {
@@ -165,13 +170,16 @@ func (h *Handlers) HandleSnapshot(w http.ResponseWriter, r *http.Request) {
}
flat, _ = bridge.BuildSnapshot(rawNodes, filter, maxDepth)
- _ = bridge.EnrichA11yNodesWithDOMMetadata(tCtx, flat)
+ if wireCarriesMetadata {
+ _ = bridge.EnrichA11yNodesWithDOMMetadata(tCtx, flat)
+ }
url, _ = h.Bridge.CurrentURL(tCtx)
title, _ = h.Bridge.CurrentTitle(tCtx)
} else {
// Unscoped: delegate to Bridge (enables ghost-chrome routing via BridgeAdapter).
result, err := h.Bridge.Snapshot(tCtx, resolvedTabID, filter, bridge.ContentParams{
- MaxDepth: maxDepth,
+ MaxDepth: maxDepth,
+ SkipMetadata: !wireCarriesMetadata,
})
if err != nil {
httpx.Error(w, 500, fmt.Errorf("snapshot: %w", err))
diff --git a/internal/handlers/snapshot_enrichment_test.go b/internal/handlers/snapshot_enrichment_test.go
new file mode 100644
index 00000000..09a88caa
--- /dev/null
+++ b/internal/handlers/snapshot_enrichment_test.go
@@ -0,0 +1,198 @@
+package handlers
+
+import (
+ "context"
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+ "time"
+
+ "github.com/chromedp/chromedp"
+ "github.com/pinchtab/pinchtab/internal/bridge"
+ "github.com/pinchtab/pinchtab/internal/config"
+ "github.com/pinchtab/pinchtab/internal/testbrowser"
+)
+
+const enrichmentFixtureHTML = `<!doctype html><html><head><title>Signup</title></head><body>
+<form>
+ <label for="email">Email</label>
+ <input id="email" type="text" placeholder="[email protected]" data-testid="signup-email">
+ <button type="submit" data-testid="checkout-submit">Continue</button>
+</form>
+</body></html>`
+
+func newEnrichmentFixture(t *testing.T) (*Handlers, string) {
+ t.Helper()
+ chromePath := testbrowser.Path(t)
+
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ w.Header().Set("Content-Type", "text/html; charset=utf-8")
+ _, _ = w.Write([]byte(enrichmentFixtureHTML))
+ }))
+ t.Cleanup(server.Close)
+
+ alloc, cancelAlloc := chromedp.NewExecAllocator(context.Background(), append(
+ chromedp.DefaultExecAllocatorOptions[:],
+ chromedp.ExecPath(chromePath),
+ chromedp.UserDataDir(testbrowser.ProfileDir(t)),
+ chromedp.Flag("headless", true),
+ chromedp.Flag("no-sandbox", true),
+ )...)
+ ctx, cancelBrowser := chromedp.NewContext(alloc)
+ ctx, cancelTimeout := context.WithTimeout(ctx, 30*time.Second)
+ t.Cleanup(func() {
+ cancelTimeout()
+ cancelBrowser()
+ cancelAlloc()
+ })
+
+ if err := chromedp.Run(ctx, chromedp.Navigate(server.URL), chromedp.WaitVisible("#email", chromedp.ByID)); err != nil {
+ t.Fatal(err)
+ }
+
+ cfg := &config.RuntimeConfig{ActionTimeout: 10 * time.Second, DefaultBrowser: config.BrowserChrome, StateDir: t.TempDir()}
+ b := bridge.New(context.Background(), ctx, cfg)
+ b.RegisterTab("tab-enrich", ctx)
+ return New(b, cfg, nil, nil, nil), "tab-enrich"
+}
+
+func snapshotFor(t *testing.T, h *Handlers, tabID, format string) string {
+ t.Helper()
+ req := httptest.NewRequest("GET", "/snapshot?tabId="+tabID+"&format="+format, nil)
+ w := httptest.NewRecorder()
+ h.HandleSnapshot(w, req)
+ if w.Code != http.StatusOK {
+ t.Fatalf("snapshot (%s): status %d body=%s", format, w.Code, w.Body.String())
+ }
+ return w.Body.String()
+}
+
+func enrichedNodes(t *testing.T, h *Handlers, tabID string) int {
+ t.Helper()
+ cache := h.Bridge.GetRefCache(tabID)
+ if cache == nil || len(cache.Nodes) == 0 {
+ t.Fatalf("no snapshot cache for %s, so nothing here observes the enrichment either way", tabID)
+ }
+ enriched := 0
+ for _, node := range cache.Nodes {
+ if node.Tag != "" || node.TestID != "" || node.Placeholder != "" {
+ enriched++
+ }
+ }
+ return enriched
+}
+
+func TestACompactSnapshotSkipsEnrichmentAndFindStillResolves(t *testing.T) {
+ h, tabID := newEnrichmentFixture(t)
+
+ body := snapshotFor(t, h, tabID, "compact")
+ if !strings.Contains(body, "textbox") {
+ t.Fatalf("the compact snapshot did not describe the form, so this proves nothing: %s", body)
+ }
+ if got := enrichedNodes(t, h, tabID); got != 0 {
+ t.Errorf("%d cached nodes carry DOM metadata after a compact snapshot; the format cannot render those fields, so the round trip that filled them was spent on nothing", got)
+ }
+
+ wantRef := refOf(t, h, tabID, "textbox", "Email")
+ findReq := httptest.NewRequest("POST", "/find", strings.NewReader(`{"tabId":"`+tabID+`","query":"[email protected]"}`))
+ findRes := httptest.NewRecorder()
+ h.HandleFind(findRes, findReq)
+ if findRes.Code != http.StatusOK {
+ t.Fatalf("find after a compact snapshot: status %d body=%s", findRes.Code, findRes.Body.String())
+ }
+
+ var found struct {
+ BestRef string `json:"best_ref"`
+ }
+ if err := json.Unmarshal(findRes.Body.Bytes(), &found); err != nil {
+ t.Fatalf("unreadable find response: %v\n%s", err, findRes.Body.String())
+ }
+ if found.BestRef != wantRef {
+ t.Errorf("find matched %q, want %q — the query is the field's placeholder, which only the DOM enrichment supplies, so a miss means the matcher scored nodes it never reached: %s",
+ found.BestRef, wantRef, findRes.Body.String())
+ }
+ if got := enrichedNodes(t, h, tabID); got == 0 {
+ t.Errorf("find left the cached nodes unenriched, so the matcher scored them without the fields it matches on")
+ }
+}
+
+func TestAJSONSnapshotStillCarriesTheMatcherFields(t *testing.T) {
+ h, tabID := newEnrichmentFixture(t)
+
+ body := snapshotFor(t, h, tabID, "json")
+ for _, field := range []string{`"tag"`, `"testid"`, `"placeholder"`} {
+ if !strings.Contains(body, field) {
+ t.Errorf("the json snapshot no longer carries %s; skipping enrichment for the cheap formats must not narrow the one that can render it:\n%s", field, body)
+ }
+ }
+ if got := enrichedNodes(t, h, tabID); got == 0 {
+ t.Errorf("a json snapshot left every cached node unenriched")
+ }
+}
+
+func refOf(t *testing.T, h *Handlers, tabID, role, name string) string {
+ t.Helper()
+ cache := h.Bridge.GetRefCache(tabID)
+ if cache == nil {
+ t.Fatal("no snapshot cache to read refs from")
+ }
+ for _, node := range cache.Nodes {
+ if node.Role == role && node.Name == name {
+ return node.Ref
+ }
+ }
+ t.Fatalf("no %s named %q in the snapshot: %+v", role, name, cache.Nodes)
+ return ""
+}
+
+type paramsCapturingBridge struct {
+ *mockBridge
+ params []bridge.ContentParams
+}
+
+func (b *paramsCapturingBridge) Snapshot(_ context.Context, _ string, _ string, params bridge.ContentParams) (*bridge.SnapshotResult, error) {
+ b.params = append(b.params, params)
+ return &bridge.SnapshotResult{
+ Nodes: []bridge.A11yNode{{Ref: "e0", Role: "button", Name: "Buy"}},
+ URL: "http://127.0.0.1:1/fixture",
+ Title: "Fixture",
+ }, nil
+}
+
+func TestTheDelegatedSnapshotAsksForMetadataOnlyWhenTheFormatCarriesIt(t *testing.T) {
+ for _, tc := range []struct {
+ format string
+ wantSkip bool
+ }{
+ {format: "compact", wantSkip: true},
+ {format: "text", wantSkip: true},
+ {format: "json", wantSkip: false},
+ {format: "yaml", wantSkip: false},
+ } {
+ t.Run(tc.format, func(t *testing.T) {
+ stub := &paramsCapturingBridge{mockBridge: &mockBridge{}}
+ h := New(stub, &config.RuntimeConfig{
+ ActionTimeout: 5 * time.Second,
+ DefaultBrowser: config.BrowserGhostChrome,
+ BrowsersAvailable: []string{config.BrowserGhostChrome},
+ StateDir: t.TempDir(),
+ }, nil, nil, nil)
+
+ req := httptest.NewRequest("GET", "/snapshot?tabId=tab1&format="+tc.format, nil)
+ w := httptest.NewRecorder()
+ h.HandleSnapshot(w, req)
+ if w.Code != http.StatusOK {
+ t.Fatalf("snapshot (%s): status %d body=%s", tc.format, w.Code, w.Body.String())
+ }
+ if len(stub.params) != 1 {
+ t.Fatalf("the delegated path ran %d times, so this case does not observe what it asks for", len(stub.params))
+ }
+ if got := stub.params[0].SkipMetadata; got != tc.wantSkip {
+ t.Errorf("format %s asked the bridge for SkipMetadata=%v, want %v; the delegated path pays the same per-node round trip the inline one does",
+ tc.format, got, tc.wantSkip)
+ }
+ })
+ }
+}
diff --git a/internal/mcp/handlers_navigation.go b/internal/mcp/handlers_navigation.go
index 2f3876e3..2eadc02f 100644
--- a/internal/mcp/handlers_navigation.go
+++ b/internal/mcp/handlers_navigation.go
@@ -109,16 +109,11 @@ func handleSnapshot(c *Client) func(context.Context, mcp.CallToolRequest) (*mcp.
if v, ok := optBool(r, "interactive"); ok && v {
q.Set("filter", "interactive")
}
- if v, ok := optBool(r, "compact"); ok && v {
- q.Set("format", "compact")
- }
- if rawFormat := optString(r, "format"); rawFormat != "" {
- format, err := normalizeSnapshotFormat(rawFormat)
- if err != nil {
- return mcp.NewToolResultError(err.Error()), nil
- }
- q.Set("format", format)
+ format, err := snapshotFormatFor(r)
+ if err != nil {
+ return mcp.NewToolResultError(err.Error()), nil
}
+ q.Set("format", format)
if v, ok := optBool(r, "diff"); ok && v {
q.Set("diff", "true")
}
@@ -142,6 +137,16 @@ func handleSnapshot(c *Client) func(context.Context, mcp.CallToolRequest) (*mcp.
}
}
+func snapshotFormatFor(r mcp.CallToolRequest) (string, error) {
+ if raw := optString(r, "format"); raw != "" {
+ return normalizeSnapshotFormat(raw)
+ }
+ if compact, ok := optBool(r, "compact"); ok && !compact {
+ return "json", nil
+ }
+ return "compact", nil
+}
+
func handleFrame(c *Client) func(context.Context, mcp.CallToolRequest) (*mcp.CallToolResult, error) {
return func(ctx context.Context, r mcp.CallToolRequest) (*mcp.CallToolResult, error) {
tabID := optString(r, "tabId")
diff --git a/internal/mcp/handlers_navigation_format_test.go b/internal/mcp/handlers_navigation_format_test.go
index 509a5c91..dea5a8a2 100644
--- a/internal/mcp/handlers_navigation_format_test.go
+++ b/internal/mcp/handlers_navigation_format_test.go
@@ -1,9 +1,12 @@
package mcp
import (
+ "net/http"
+ "net/http/httptest"
"net/url"
"testing"
+ "github.com/mark3labs/mcp-go/mcp"
"github.com/pinchtab/pinchtab/internal/handlers"
)
@@ -39,3 +42,55 @@ func TestMCPNarrowsTheHandlerRatherThanDivergingFromIt(t *testing.T) {
}
}
}
+
+func snapshotQueryFor(t *testing.T, args map[string]any) (url.Values, *mcp.CallToolResult) {
+ t.Helper()
+ var captured url.Values
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ captured = r.URL.Query()
+ _, _ = w.Write([]byte("# snapshot\n"))
+ }))
+ t.Cleanup(srv.Close)
+ result := callTool(t, "pinchtab_snapshot", args, srv)
+ return captured, result
+}
+
+func TestTheSnapshotToolAsksForCompactUnlessToldOtherwise(t *testing.T) {
+ for _, tc := range []struct {
+ name string
+ args map[string]any
+ want string
+ }{
+ {name: "no format argument at all", args: map[string]any{}, want: "compact"},
+ {name: "interactive only", args: map[string]any{"interactive": true}, want: "compact"},
+ {name: "compact asked for explicitly", args: map[string]any{"compact": true}, want: "compact"},
+ {name: "compact declined", args: map[string]any{"compact": false}, want: "json"},
+ {name: "format wins over the default", args: map[string]any{"format": "text"}, want: "text"},
+ {name: "format wins over compact", args: map[string]any{"format": "text", "compact": true}, want: "text"},
+ {name: "format normalised", args: map[string]any{"format": " COMPACT "}, want: "compact"},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ query, result := snapshotQueryFor(t, tc.args)
+ if result.IsError {
+ t.Fatalf("the tool refused %v: %s", tc.args, resultText(t, result))
+ }
+ if got := query.Get("format"); got != tc.want {
+ t.Errorf("the tool asked /snapshot for format=%q, want %q; the agent pays for the answer the server actually sends, not for the one the source reads like",
+ got, tc.want)
+ }
+ if _, err := handlers.ParseSnapshotCostControls(query); err != nil {
+ t.Errorf("the server rejects the query this tool sends: %v (query=%v)", err, query)
+ }
+ })
+ }
+}
+
+func TestTheSnapshotToolRefusesAFormatBeforeSendingIt(t *testing.T) {
+ query, result := snapshotQueryFor(t, map[string]any{"format": "xml"})
+ if !result.IsError {
+ t.Fatalf("format=xml was accepted; the caller gets an answer to a question it did not ask")
+ }
+ if query != nil {
+ t.Errorf("the tool reached the server anyway with %v", query)
+ }
+}
diff --git a/internal/mcp/tools.go b/internal/mcp/tools.go
index 9263d5eb..96321cfb 100644
--- a/internal/mcp/tools.go
+++ b/internal/mcp/tools.go
@@ -47,7 +47,7 @@ func allTools() []mcp.Tool {
mcp.WithDescription("Get an accessibility tree snapshot of the current page. Use this sparingly: prefer pinchtab_find + action selectors for faster loops."),
tabIDParam(),
mcp.WithBoolean("interactive", mcp.Description("Only interactive elements (buttons, links, inputs)")),
- mcp.WithBoolean("compact", mcp.Description("Compact format (most token-efficient)")),
+ mcp.WithBoolean("compact", mcp.Description("Compact format (default; false=JSON)")),
mcp.WithString("format", mcp.Description("Output format: 'compact' or 'text'")),
mcp.WithBoolean("diff", mcp.Description("Only changes since last snapshot")),
mcp.WithString("selector", mcp.Description("Unified selector to scope the snapshot (ref, CSS, XPath, text, find, role, label, placeholder, alt, title, testid, first/last/nth). Selectors resolve in the current frame scope; use pinchtab_frame for iframe content."+positionalWrapperGrammar)),