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.goindex 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.gonew file mode 100644index 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.mdindex 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.mdindex 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 whosediff --git a/internal/bridge/bridge.go b/internal/bridge/bridge.goindex 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, paramaxDepth = -1}nodes, refs := BuildSnapshot(rawNodes, filter, maxDepth)- _ = EnrichA11yNodesWithDOMMetadata(ctx, nodes)+ if !params.SkipMetadata {+ _ = EnrichA11yNodesWithDOMMetadata(ctx, nodes)+ }targets := RefTargetsFromNodes(nodes)var url stringdiff --git a/internal/bridge/bridge_types.go b/internal/bridge/bridge_types.goindex 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.ScannerMaxDepth 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.goindex 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.BackendDOMNodeIDdiff --git a/internal/bridge/password_mask_browser_test.go b/internal/bridge/password_mask_browser_test.goindex cc7f4e79..ac382a52 100644--- a/internal/bridge/password_mask_browser_test.go+++ b/internal/bridge/password_mask_browser_test.go@@ -3,6 +3,7 @@ package bridgeimport ("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.gonew file mode 100644index 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.goindex 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, selecif 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, selecresult := 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.goindex 45b83d1b..c955cc1a 100644--- a/internal/cli/actions/actions_snapshot_test.go+++ b/internal/cli/actions/actions_snapshot_test.go@@ -1,16 +1,20 @@package actionsimport (+ "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.goindex 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.MaxDepthmaxTokens := 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.gonew file mode 100644index 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 := ¶msCapturingBridge{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.goindex 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.goindex 509a5c91..dea5a8a2 100644--- a/internal/mcp/handlers_navigation_format_test.go+++ b/internal/mcp/handlers_navigation_format_test.go@@ -1,9 +1,12 @@package mcpimport (+ "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.goindex 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)),