@ulpi/browse 1.0.6 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +109 -2
  2. package/dist/browse.cjs +5104 -2105
  3. package/package.json +5 -5
  4. package/skill/SKILL.md +132 -318
  5. package/skill/references/commands.md +482 -0
  6. package/skill/references/guides.md +178 -0
  7. package/skill/references/permissions.md +51 -0
  8. package/BENCHMARKS.md +0 -222
package/skill/references/permissions.md ADDED
@@ -0,0 +1,51 @@
1
+ # browse — Permission Rules for Claude Code
2
+
3
+ Add these rules to `.claude/settings.json` under `permissions.allow` to pre-allow all browse commands. Merge with existing rules — do not overwrite.
4
+
5
+ ```json
6
+ "Bash(browse:*)",
7
+ "Bash(browse goto:*)", "Bash(browse back:*)", "Bash(browse forward:*)",
8
+ "Bash(browse reload:*)", "Bash(browse url:*)", "Bash(browse text:*)",
9
+ "Bash(browse html:*)", "Bash(browse links:*)", "Bash(browse forms:*)",
10
+ "Bash(browse accessibility:*)", "Bash(browse snapshot:*)",
11
+ "Bash(browse snapshot-diff:*)", "Bash(browse click:*)",
12
+ "Bash(browse dblclick:*)", "Bash(browse fill:*)", "Bash(browse select:*)",
13
+ "Bash(browse hover:*)", "Bash(browse focus:*)",
14
+ "Bash(browse check:*)", "Bash(browse uncheck:*)",
15
+ "Bash(browse type:*)", "Bash(browse press:*)",
16
+ "Bash(browse keydown:*)", "Bash(browse keyup:*)",
17
+ "Bash(browse scroll:*)", "Bash(browse wait:*)",
18
+ "Bash(browse viewport:*)", "Bash(browse upload:*)",
19
+ "Bash(browse drag:*)", "Bash(browse highlight:*)", "Bash(browse download:*)",
20
+ "Bash(browse dialog-accept:*)", "Bash(browse dialog-dismiss:*)",
21
+ "Bash(browse js:*)", "Bash(browse eval:*)", "Bash(browse css:*)",
22
+ "Bash(browse attrs:*)", "Bash(browse element-state:*)", "Bash(browse dialog:*)",
23
+ "Bash(browse console:*)", "Bash(browse network:*)",
24
+ "Bash(browse cookies:*)", "Bash(browse storage:*)", "Bash(browse perf:*)",
25
+ "Bash(browse value:*)", "Bash(browse count:*)",
26
+ "Bash(browse devices:*)", "Bash(browse emulate:*)",
27
+ "Bash(browse screenshot:*)", "Bash(browse pdf:*)",
28
+ "Bash(browse responsive:*)", "Bash(browse diff:*)",
29
+ "Bash(browse chain:*)", "Bash(browse tabs:*)", "Bash(browse tab:*)",
30
+ "Bash(browse newtab:*)", "Bash(browse closetab:*)",
31
+ "Bash(browse frame:*)",
32
+ "Bash(browse sessions:*)", "Bash(browse session-close:*)",
33
+ "Bash(browse state:*)", "Bash(browse auth:*)", "Bash(browse har:*)", "Bash(browse video:*)",
34
+ "Bash(browse record:*)",
35
+ "Bash(browse route:*)", "Bash(browse offline:*)",
36
+ "Bash(browse status:*)", "Bash(browse stop:*)", "Bash(browse restart:*)",
37
+ "Bash(browse cookie:*)", "Bash(browse header:*)",
38
+ "Bash(browse useragent:*)",
39
+ "Bash(browse clipboard:*)", "Bash(browse screenshot-diff:*)",
40
+ "Bash(browse find:*)", "Bash(browse inspect:*)",
41
+ "Bash(browse instances:*)", "Bash(browse --headed:*)",
42
+ "Bash(browse rightclick:*)", "Bash(browse tap:*)",
43
+ "Bash(browse swipe:*)", "Bash(browse mouse:*)",
44
+ "Bash(browse keyboard:*)", "Bash(browse scrollinto:*)",
45
+ "Bash(browse scrollintoview:*)", "Bash(browse set:*)",
46
+ "Bash(browse box:*)", "Bash(browse errors:*)",
47
+ "Bash(browse doctor:*)", "Bash(browse upgrade:*)",
48
+ "Bash(browse --max-output:*)",
49
+ "Bash(browse handoff:*)", "Bash(browse resume:*)",
50
+ "Bash(browse react-devtools:*)", "Bash(browse profile:*)"
51
+ ```
package/BENCHMARKS.md DELETED
@@ -1,222 +0,0 @@
1
- # Benchmarks: @ulpi/browse vs @playwright/mcp
2
-
3
- Measured 2026-03-15. Same machine, same Chromium, same pages.
4
-
5
- ## What Gets Dumped Into the AI Context
6
-
7
- **@playwright/mcp**: Every `browser_navigate`, `browser_click`, or `browser_type` returns the **full accessibility snapshot** — automatically, whether you need it or not.
8
-
9
- **@ulpi/browse**: `goto` returns a one-liner (`"Navigated to ... (200)"`). The agent **chooses** what to request: `text`, `snapshot -i`, `links`, `forms`, etc.
10
-
11
- ## Per-Page Token Cost
12
-
13
- | Site | Page | @playwright/mcp navigate | browse snapshot -i | Ratio |
14
- |------|------|-------------------------:|-------------------:|------:|
15
- | mumzworld.com | Homepage | ~51,151 | ~15,072 | **3x** |
16
- | mumzworld.com | Search | ~13,860 | ~3,614 | **4x** |
17
- | mumzworld.com | PDP | ~10,071 | ~3,084 | **3x** |
18
- | amazon.com | Homepage | ~10,431 | ~2,150 | **5x** |
19
- | amazon.com | Search | ~19,458 | ~3,644 | **5x** |
20
- | ebay.com | Homepage | ~4,641 | ~1,557 | **3x** |
21
- | ebay.com | Search | ~35,929 | ~7,088 | **5x** |
22
- | ebay.com | PDP | ~1,294 | ~678 | **2x** |
23
- | nike.com | Homepage | ~2,495 | ~816 | **3x** |
24
- | nike.com | Search | ~7,998 | ~2,678 | **3x** |
25
- | nike.com | PDP | ~3,034 | ~989 | **3x** |
26
- | **TOTAL** | **11 pages** | **~160,362** | **~41,370** | **4x** |
27
-
28
- `browse goto` alone costs ~10-25 tokens per navigation (one-liner confirmation). The agent requests a snapshot only when it needs to see the page.
29
-
30
- ## 10-Step Agent Session
31
-
32
- A typical flow: navigate, snapshot, click, snapshot, fill, click, snapshot, check result.
33
-
34
- | | @playwright/mcp | @ulpi/browse |
35
- |---|---:|---:|
36
- | Tokens per navigate/click/type | ~14,578 (auto-dumped) | ~15 (one-liner) |
37
- | 10 actions total | ~145,780 | ~11,388 (3 snapshots + 7 actions) |
38
- | Context consumed (200K window) | 73% | 6% |
39
-
40
- ## Raw Data
41
-
42
- ### mumzworld.com
43
-
44
- #### Homepage
45
-
46
- | Approach | Size | ~Tokens | Notes |
47
- |----------|-----:|--------:|-------|
48
- | @playwright/mcp navigate | 199.8 KB | ~51,151 | Full snapshot auto-dumped |
49
- | Playwright page.content() | 3.50 MB | ~917,905 | Raw HTML |
50
- | browse goto | 44 B | ~11 | One-liner |
51
- | browse text | 19.4 KB | ~4,971 | Clean visible text |
52
- | browse snapshot | 159.5 KB | ~40,844 | Full tree + @refs |
53
- | **browse snapshot -i** | **58.9 KB** | **~15,072** | **Interactive + @refs** |
54
- | browse links | 62.2 KB | ~15,913 | Text → URL |
55
- | browse forms | 213 B | ~53 | Structured JSON |
56
-
57
- #### Search
58
-
59
- | Approach | Size | ~Tokens | Notes |
60
- |----------|-----:|--------:|-------|
61
- | @playwright/mcp navigate | 54.1 KB | ~13,860 | Full snapshot auto-dumped |
62
- | Playwright page.content() | 1.08 MB | ~283,764 | Raw HTML |
63
- | browse goto | 66 B | ~17 | One-liner |
64
- | browse text | 6.6 KB | ~1,687 | Clean visible text |
65
- | browse snapshot | 49.2 KB | ~12,585 | Full tree + @refs |
66
- | **browse snapshot -i** | **14.1 KB** | **~3,614** | **Interactive + @refs** |
67
- | browse links | 14.0 KB | ~3,587 | Text → URL |
68
- | browse forms | 305 B | ~76 | Structured JSON |
69
-
70
- #### PDP
71
-
72
- | Approach | Size | ~Tokens | Notes |
73
- |----------|-----:|--------:|-------|
74
- | @playwright/mcp navigate | 39.3 KB | ~10,071 | Full snapshot auto-dumped |
75
- | Playwright page.content() | 1.48 MB | ~387,614 | Raw HTML |
76
- | browse goto | 101 B | ~25 | One-liner |
77
- | browse text | 6.9 KB | ~1,767 | Clean visible text |
78
- | browse snapshot | 33.2 KB | ~8,508 | Full tree + @refs |
79
- | **browse snapshot -i** | **12.0 KB** | **~3,084** | **Interactive + @refs** |
80
- | browse links | 12.5 KB | ~3,203 | Text → URL |
81
- | browse forms | 545 B | ~136 | Structured JSON |
82
-
83
- ### amazon.com
84
-
85
- #### Homepage
86
-
87
- | Approach | Size | ~Tokens | Notes |
88
- |----------|-----:|--------:|-------|
89
- | @playwright/mcp navigate | 40.7 KB | ~10,431 | Full snapshot auto-dumped |
90
- | Playwright page.content() | 584.2 KB | ~149,544 | Raw HTML |
91
- | browse goto | 41 B | ~10 | One-liner |
92
- | browse text | 4.7 KB | ~1,192 | Clean visible text |
93
- | browse snapshot | 19.6 KB | ~5,008 | Full tree + @refs |
94
- | **browse snapshot -i** | **8.4 KB** | **~2,150** | **Interactive + @refs** |
95
- | browse links | 38.5 KB | ~9,853 | Text → URL |
96
- | browse forms | 4.2 KB | ~1,075 | Structured JSON |
97
-
98
- #### Search
99
-
100
- | Approach | Size | ~Tokens | Notes |
101
- |----------|-----:|--------:|-------|
102
- | @playwright/mcp navigate | 76.0 KB | ~19,458 | Full snapshot auto-dumped |
103
- | Playwright page.content() | 673.5 KB | ~172,417 | Raw HTML |
104
- | browse goto | 59 B | ~15 | One-liner |
105
- | browse text | 8.1 KB | ~2,069 | Clean visible text |
106
- | browse snapshot | 29.1 KB | ~7,446 | Full tree + @refs |
107
- | **browse snapshot -i** | **14.2 KB** | **~3,644** | **Interactive + @refs** |
108
- | browse links | 49.7 KB | ~12,712 | Text → URL |
109
- | browse forms | 5.4 KB | ~1,377 | Structured JSON |
110
-
111
- ### ebay.com
112
-
113
- #### Homepage
114
-
115
- | Approach | Size | ~Tokens | Notes |
116
- |----------|-----:|--------:|-------|
117
- | @playwright/mcp navigate | 18.1 KB | ~4,641 | Full snapshot auto-dumped |
118
- | Playwright page.content() | 1.70 MB | ~445,637 | Raw HTML |
119
- | browse goto | 39 B | ~10 | One-liner |
120
- | browse text | 4.9 KB | ~1,245 | Clean visible text |
121
- | browse snapshot | 10.6 KB | ~2,715 | Full tree + @refs |
122
- | **browse snapshot -i** | **6.1 KB** | **~1,557** | **Interactive + @refs** |
123
- | browse links | 29.4 KB | ~7,533 | Text → URL |
124
- | browse forms | 3.9 KB | ~1,006 | Structured JSON |
125
-
126
- #### Search
127
-
128
- | Approach | Size | ~Tokens | Notes |
129
- |----------|-----:|--------:|-------|
130
- | @playwright/mcp navigate | 140.3 KB | ~35,929 | Full snapshot auto-dumped |
131
- | Playwright page.content() | 1.26 MB | ~331,247 | Raw HTML |
132
- | browse goto | 69 B | ~17 | One-liner |
133
- | browse text | 17.7 KB | ~4,526 | Clean visible text |
134
- | browse snapshot | 57.6 KB | ~14,750 | Full tree + @refs |
135
- | **browse snapshot -i** | **27.7 KB** | **~7,088** | **Interactive + @refs** |
136
- | browse links | 61.9 KB | ~15,851 | Text → URL |
137
- | browse forms | 4.4 KB | ~1,124 | Structured JSON |
138
-
139
- #### PDP
140
-
141
- | Approach | Size | ~Tokens | Notes |
142
- |----------|-----:|--------:|-------|
143
- | @playwright/mcp navigate | 5.1 KB | ~1,294 | Full snapshot auto-dumped |
144
- | Playwright page.content() | 1.07 MB | ~279,725 | Raw HTML |
145
- | browse goto | 56 B | ~14 | One-liner |
146
- | browse text | 1.2 KB | ~315 | Clean visible text |
147
- | browse snapshot | 3.5 KB | ~889 | Full tree + @refs |
148
- | **browse snapshot -i** | **2.6 KB** | **~678** | **Interactive + @refs** |
149
- | browse links | 7.6 KB | ~1,934 | Text → URL |
150
- | browse forms | 3.9 KB | ~1,006 | Structured JSON |
151
-
152
- ### nike.com
153
-
154
- #### Homepage
155
-
156
- | Approach | Size | ~Tokens | Notes |
157
- |----------|-----:|--------:|-------|
158
- | @playwright/mcp navigate | 9.7 KB | ~2,495 | Full snapshot auto-dumped |
159
- | Playwright page.content() | 700.4 KB | ~179,315 | Raw HTML |
160
- | browse goto | 39 B | ~10 | One-liner |
161
- | browse text | 2.4 KB | ~607 | Clean visible text |
162
- | browse snapshot | 5.1 KB | ~1,315 | Full tree + @refs |
163
- | **browse snapshot -i** | **3.2 KB** | **~816** | **Interactive + @refs** |
164
- | browse links | 30.2 KB | ~7,744 | Text → URL |
165
- | browse forms | 1.3 KB | ~341 | Structured JSON |
166
-
167
- #### Search
168
-
169
- | Approach | Size | ~Tokens | Notes |
170
- |----------|-----:|--------:|-------|
171
- | @playwright/mcp navigate | 31.2 KB | ~7,998 | Full snapshot auto-dumped |
172
- | Playwright page.content() | 1.08 MB | ~282,582 | Raw HTML |
173
- | browse goto | 57 B | ~14 | One-liner |
174
- | browse text | 5.9 KB | ~1,502 | Clean visible text |
175
- | browse snapshot | 16.2 KB | ~4,152 | Full tree + @refs |
176
- | **browse snapshot -i** | **10.5 KB** | **~2,678** | **Interactive + @refs** |
177
- | browse links | 26.6 KB | ~6,798 | Text → URL |
178
- | browse forms | 291 B | ~73 | Structured JSON |
179
-
180
- #### PDP
181
-
182
- | Approach | Size | ~Tokens | Notes |
183
- |----------|-----:|--------:|-------|
184
- | @playwright/mcp navigate | 11.9 KB | ~3,034 | Full snapshot auto-dumped |
185
- | Playwright page.content() | 972.4 KB | ~248,945 | Raw HTML |
186
- | browse goto | 81 B | ~20 | One-liner |
187
- | browse text | 5.1 KB | ~1,313 | Clean visible text |
188
- | browse snapshot | 9.0 KB | ~2,314 | Full tree + @refs |
189
- | **browse snapshot -i** | **3.9 KB** | **~989** | **Interactive + @refs** |
190
- | browse links | 24.2 KB | ~6,205 | Text → URL |
191
- | browse forms | 283 B | ~71 | Structured JSON |
192
-
193
- ## Architectural Differences
194
-
195
- | | @playwright/mcp | @ulpi/browse |
196
- |---|---|---|
197
- | **Navigate response** | Full snapshot (~5-50K tokens) | One-liner (~15 tokens) |
198
- | **Click/type response** | Full snapshot (~5-50K tokens) | One-liner (~15 tokens) |
199
- | **Agent controls output** | No — always gets full dump | Yes — requests what it needs |
200
- | **Interactive-only filter** | No | `snapshot -i` |
201
- | **Cursor-interactive detection** | No | `snapshot -C` (cursor:pointer, onclick, tabindex) |
202
- | **Clean text extraction** | No | `text` command |
203
- | **Form discovery** | No | `forms` command |
204
- | **Link extraction** | No | `links` command |
205
- | **Network/console logs** | console_messages only | `network` + `console` |
206
- | **Performance timing** | No | `perf` command |
207
- | **Cookies/storage** | No | `cookies` + `storage` |
208
- | **Snapshot diff** | No | `snapshot-diff` |
209
- | **Page text diff** | No | `diff <url1> <url2>` |
210
- | **Responsive screenshots** | No | `responsive` (3 viewports) |
211
- | **Persistent daemon** | No — new browser per session | Yes — ~100ms per command |
212
- | **Crash recovery** | No | Auto-restart with safe retry |
213
- | **Total commands** | ~15 tools | 40+ commands |
214
-
215
- ## Methodology
216
-
217
- - Token estimates: ~4 chars per token (standard approximation)
218
- - @playwright/mcp: simulated by calling `ariaSnapshot()` after navigation (identical to what the MCP server does internally)
219
- - All pages loaded with `waitUntil: domcontentloaded` + 2.5s settle
220
- - Pages returning < 200 bytes excluded (bot detection)
221
- - Measured 2026-03-15, Playwright 1.58.2, Chromium headless
222
- - Rerun: `bun run benchmark.ts`