cbrowser 18.42.6 → 18.42.7
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.
- package/README.md +166 -351
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,106 +1,90 @@
|
|
|
1
1
|
# CBrowser — Cognitive Browser Automation
|
|
2
2
|
|
|
3
|
-
> **The browser automation that thinks
|
|
3
|
+
> **The browser automation that thinks like your users.** 108 MCP tools. 26 cognitive traits. 11 disability personas. The only framework that predicts when users give up.
|
|
4
4
|
|
|
5
5
|
[](https://www.npmjs.com/package/cbrowser)
|
|
6
6
|
[](https://cbrowser.ai/docs)
|
|
7
|
-
[](docs/STRESS-TEST-v16.14.4.md)
|
|
8
7
|
[](LICENSE)
|
|
9
8
|
[](https://modelcontextprotocol.io)
|
|
10
9
|
[](https://www.typescriptlang.org/)
|
|
11
10
|
[](https://nodejs.org/)
|
|
12
11
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
---
|
|
18
|
-
|
|
19
|
-
## What Makes CBrowser Different
|
|
20
|
-
|
|
21
|
-
**108 MCP tools, 26 cognitive traits, 10 motivational values, 17 cognitive + 8 marketing personas.** After rigorous stress testing across production sites including Airbnb and Hacker News:
|
|
22
|
-
|
|
23
|
-
| Capability | Status | Why It Matters |
|
|
24
|
-
|------------|--------|----------------|
|
|
25
|
-
| **Natural Language Tests** | ⭐ Best-in-class | Write tests in plain English. 10-step E2E flows run 100% stable. |
|
|
26
|
-
| **Cognitive User Simulation** | 🔬 Novel | 26 research-backed traits model real human behavior—not just clicks. |
|
|
27
|
-
| **Empathy Accessibility Audits** | 🔬 Novel | Simulate users with tremors, low vision, ADHD. No competitor offers this. |
|
|
28
|
-
| **Self-Healing Selectors** | ✅ Production-ready | ARIA-first with 0.8+ confidence gating. Handles DOM changes automatically. |
|
|
29
|
-
| **Constitutional AI Safety** | 🔬 Novel | Risk-classified actions prevent autonomous agents from doing damage. |
|
|
30
|
-
| **108 MCP Tools** | ✅ Production-ready | Full Claude integration—local and remote servers. |
|
|
12
|
+
```bash
|
|
13
|
+
npm install cbrowser
|
|
14
|
+
npx cbrowser cognitive-effort --url "https://your-site.com" --persona first-timer
|
|
15
|
+
```
|
|
31
16
|
|
|
32
17
|
---
|
|
33
18
|
|
|
34
|
-
##
|
|
19
|
+
## Cognitive Transport Chain
|
|
35
20
|
|
|
36
|
-
|
|
21
|
+
The 6-layer Sequential Transport Chain computes exactly how hard your page is for any persona — and predicts whether they'll abandon:
|
|
37
22
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
23
|
+
| Layer | What It Measures | Research Basis |
|
|
24
|
+
|-------|-----------------|----------------|
|
|
25
|
+
| **Saliency** | Visual attention capture | CIE-Lab W₂ perceptual model |
|
|
26
|
+
| **Cognitive Load** | Information processing demand | Sweller (1988) CLT |
|
|
27
|
+
| **Decision** | Choice complexity and fatigue | Hick-Hyman Law |
|
|
28
|
+
| **Motor** | Physical interaction difficulty | Grossman & Balakrishnan (2005) |
|
|
29
|
+
| **Frustration** | Emotional cost accumulation | Ceaparu et al. (2004) |
|
|
30
|
+
| **Readability** | Text comprehension effort | Perry & Zorzi (2013) reading model |
|
|
43
31
|
|
|
44
|
-
|
|
32
|
+
```bash
|
|
33
|
+
npx cbrowser cognitive-effort --url "https://your-site.com" --persona first-timer
|
|
34
|
+
# → CTC: 0.76, abandonment risk: 42%, bottleneck: decision
|
|
35
|
+
```
|
|
45
36
|
|
|
46
|
-
|
|
47
|
-
|-----------|-------------------|----------|
|
|
48
|
-
| **User behavior** | Simulates clicks and keystrokes | **Simulates human cognition**—patience decay, frustration accumulation, decision fatigue |
|
|
49
|
-
| **Abandonment prediction** | Fails when elements don't exist | **Predicts when users give up** before they do |
|
|
50
|
-
| **AI agent safety** | No guardrails for autonomous agents | **Constitutional AI safety**—risk-classified actions with verification gates |
|
|
51
|
-
| **Selector resilience** | Breaks when DOM changes | **Self-healing ARIA-first selectors** with 0.8+ confidence gating |
|
|
52
|
-
| **Accessibility testing** | WCAG compliance checklists | **Disability empathy simulation**—experience your site as a user with tremors, low vision, or ADHD |
|
|
37
|
+
Returns: total CTC score, per-layer breakdown, bottleneck identification, abandonment risk percentage, and motor accessibility overlay.
|
|
53
38
|
|
|
54
39
|
---
|
|
55
40
|
|
|
56
|
-
##
|
|
41
|
+
## Visual Overlays & Attention Analysis
|
|
57
42
|
|
|
58
|
-
|
|
43
|
+
See where users look, what they miss, and whether your CTAs capture attention — per persona:
|
|
59
44
|
|
|
60
45
|
```bash
|
|
61
|
-
|
|
62
|
-
npx
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
### First Commands
|
|
46
|
+
# Full visual cognitive story — 4 annotated images + narrative
|
|
47
|
+
npx cbrowser visual-cognitive-story --url "https://your-site.com" --persona cognitive-adhd
|
|
66
48
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
npx cbrowser navigate "https://your-site.com"
|
|
49
|
+
# Attention heatmap — where does this persona look?
|
|
50
|
+
npx cbrowser attention-analysis --url "https://your-site.com" --persona first-timer
|
|
70
51
|
|
|
71
|
-
#
|
|
72
|
-
npx cbrowser
|
|
52
|
+
# Compare how two personas experience the same page
|
|
53
|
+
npx cbrowser attention-compare --url "https://your-site.com" --persona-a first-timer --persona-b power-user
|
|
54
|
+
```
|
|
73
55
|
|
|
74
|
-
|
|
75
|
-
|
|
56
|
+
**Overlays generated:**
|
|
57
|
+
- **Attention heatmap** — CIE-Lab saliency on grayscale base (red = high attention)
|
|
58
|
+
- **Motor accessibility** — Green/yellow/red per element by P(hit)
|
|
59
|
+
- **Attention quality** — CTAs green, distractors red, headings blue
|
|
60
|
+
- **Comparison diff** — Blue = persona A attention, red = persona B
|
|
76
61
|
|
|
77
|
-
|
|
78
|
-
npx cbrowser cognitive-journey \
|
|
79
|
-
--persona first-timer \
|
|
80
|
-
--start "https://your-site.com" \
|
|
81
|
-
--goal "complete checkout"
|
|
82
|
-
```
|
|
62
|
+
**Metrics:** CTA capture rate, value prop salience, distractor ratio, quality score (0-100), entropy.
|
|
83
63
|
|
|
84
64
|
---
|
|
85
65
|
|
|
86
|
-
##
|
|
66
|
+
## AI Friendliness Suite
|
|
87
67
|
|
|
88
|
-
|
|
68
|
+
Five tools to make your site ready for the AI agent era:
|
|
89
69
|
|
|
90
|
-
|
|
|
91
|
-
|
|
92
|
-
|
|
|
93
|
-
|
|
|
94
|
-
|
|
|
95
|
-
|
|
|
70
|
+
| Tool | What It Does |
|
|
71
|
+
|------|-------------|
|
|
72
|
+
| `agent_ready_audit` | Score site on findability, stability, accessibility, semantics (A-F grade) |
|
|
73
|
+
| `ai_benchmark` | Compare AI-friendliness across competitor URLs |
|
|
74
|
+
| `webmcp_ready_audit` | Audit MCP server for WebMCP compatibility |
|
|
75
|
+
| `remediation_patches` | Generate actionable code fixes for audit findings |
|
|
76
|
+
| `llms_txt_generate` | Generate AI-readable llms.txt site description |
|
|
96
77
|
|
|
97
|
-
|
|
78
|
+
```bash
|
|
79
|
+
npx cbrowser agent-ready-audit "https://your-site.com" --html
|
|
80
|
+
npx cbrowser ai-benchmark "https://site-a.com,https://site-b.com"
|
|
81
|
+
```
|
|
98
82
|
|
|
99
83
|
---
|
|
100
84
|
|
|
101
85
|
## Cognitive User Simulation
|
|
102
86
|
|
|
103
|
-
|
|
87
|
+
**26 research-backed cognitive traits + 10 motivational values** model how real users think, struggle, and give up:
|
|
104
88
|
|
|
105
89
|
| Trait | Research Basis | What It Models |
|
|
106
90
|
|-------|---------------|----------------|
|
|
@@ -115,28 +99,29 @@ CBrowser models **25 research-backed cognitive traits** across 6 tiers to simula
|
|
|
115
99
|
| **Social Proof** | Cialdini (2001) | Influence of reviews, ratings, popularity indicators |
|
|
116
100
|
| **FOMO** | Przybylski et al. (2013) | Fear of missing out; urgency and scarcity responses |
|
|
117
101
|
|
|
118
|
-
*See [Trait Index](https://
|
|
102
|
+
*See [Trait Index](https://cbrowser.ai/docs/Trait-Index) for all 26 traits including: Persistence, Resilience, Curiosity, Change Blindness, Anchoring Bias, Time Horizon, Attribution Style, Metacognitive Planning, Procedural Fluency, Transfer Learning, Authority Sensitivity, Emotional Contagion, Mental Model Rigidity, Interrupt Recovery, Reading Tendency, and Site Familiarity.*
|
|
119
103
|
|
|
120
|
-
|
|
104
|
+
**Full documentation:** [Research Methodology](https://cbrowser.ai/docs/Research-Methodology) · [Trait Index](https://cbrowser.ai/docs/Trait-Index) · [Bibliography](https://cbrowser.ai/docs/Bibliography)
|
|
121
105
|
|
|
122
|
-
|
|
106
|
+
### 17 Built-in Personas
|
|
123
107
|
|
|
124
|
-
|
|
108
|
+
**6 general:** first-timer, power-user, mobile-user, screen-reader-user, elderly-user, impatient-user
|
|
125
109
|
|
|
126
|
-
|
|
110
|
+
**11 accessibility:** motor-impairment-tremor, low-vision-magnified, cognitive-adhd, dyslexic-user, deaf-user, elderly-low-vision, color-blind-deuteranopia, autism-spectrum, intellectual-disability, aphasia-receptive, dyscalculia
|
|
127
111
|
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
Reason: Patience depleted (0.08) - "This is taking too long..."
|
|
132
|
-
Friction points:
|
|
133
|
-
1. Password requirements unclear (step 4)
|
|
134
|
-
2. Form validation error not visible (step 6)
|
|
135
|
-
```
|
|
112
|
+
### Values System
|
|
113
|
+
|
|
114
|
+
Beyond cognitive traits, CBrowser models **10 motivational values** from three psychological frameworks:
|
|
136
115
|
|
|
137
|
-
|
|
116
|
+
| Framework | Research Basis |
|
|
117
|
+
|-----------|---------------|
|
|
118
|
+
| **Schwartz's Universal Values** | Schwartz (1992) — 10 core values: Power, Achievement, Hedonism, Stimulation, Self-Direction, Universalism, Benevolence, Tradition, Conformity, Security |
|
|
119
|
+
| **Self-Determination Theory** | Deci & Ryan (1985) — Autonomy, Competence, Relatedness |
|
|
120
|
+
| **Maslow's Hierarchy** | Maslow (1943) — 5 need levels |
|
|
138
121
|
|
|
139
|
-
|
|
122
|
+
See [Values Framework](https://cbrowser.ai/docs/Values-Framework) for full documentation.
|
|
123
|
+
|
|
124
|
+
### Custom Persona Builder
|
|
140
125
|
|
|
141
126
|
```bash
|
|
142
127
|
# Interactive questionnaire (8 core traits)
|
|
@@ -145,52 +130,62 @@ npx cbrowser persona-questionnaire start
|
|
|
145
130
|
# Comprehensive questionnaire (all 26 traits)
|
|
146
131
|
npx cbrowser persona-questionnaire start --comprehensive --name "my-tester"
|
|
147
132
|
|
|
148
|
-
#
|
|
149
|
-
npx cbrowser persona-
|
|
150
|
-
|
|
151
|
-
# List all available traits
|
|
152
|
-
npx cbrowser persona-questionnaire list-traits
|
|
133
|
+
# From a description — AI generates trait values
|
|
134
|
+
npx cbrowser persona-create "A 68-year-old retiree who just got their first smartphone"
|
|
153
135
|
```
|
|
154
136
|
|
|
155
|
-
|
|
137
|
+
### Abandonment Detection
|
|
156
138
|
|
|
157
|
-
|
|
139
|
+
The simulation stops when a realistic user would give up:
|
|
158
140
|
|
|
159
|
-
|
|
141
|
+
```bash
|
|
142
|
+
⚠️ ABANDONED after 8 steps
|
|
143
|
+
Reason: Patience depleted (0.08) - "This is taking too long..."
|
|
144
|
+
Friction points:
|
|
145
|
+
1. Password requirements unclear (step 4)
|
|
146
|
+
2. Form validation error not visible (step 6)
|
|
147
|
+
```
|
|
160
148
|
|
|
161
|
-
|
|
162
|
-
|-----------|---------------|----------------|
|
|
163
|
-
| **Schwartz's Universal Values** | Schwartz (1992) | 10 core human values: Power, Achievement, Hedonism, Stimulation, Self-Direction, Universalism, Benevolence, Tradition, Conformity, Security |
|
|
164
|
-
| **Self-Determination Theory** | Deci & Ryan (1985) | Autonomy, Competence, and Relatedness needs that drive intrinsic motivation |
|
|
165
|
-
| **Maslow's Hierarchy** | Maslow (1943) | 5 need levels from Physiological to Self-Actualization |
|
|
149
|
+
---
|
|
166
150
|
|
|
167
|
-
|
|
151
|
+
## Accessibility Empathy Testing
|
|
168
152
|
|
|
169
|
-
|
|
170
|
-
# Look up a persona's values profile
|
|
171
|
-
npx cbrowser persona-values power-user
|
|
153
|
+
Simulate how users with disabilities experience your site:
|
|
172
154
|
|
|
173
|
-
|
|
155
|
+
```bash
|
|
156
|
+
npx cbrowser empathy-audit "https://your-site.com" \
|
|
157
|
+
--goal "complete signup" \
|
|
158
|
+
--disabilities "motor-impairment-tremor" \
|
|
159
|
+
--html
|
|
174
160
|
```
|
|
175
161
|
|
|
176
|
-
|
|
162
|
+
---
|
|
177
163
|
|
|
178
|
-
|
|
164
|
+
## Constitutional AI Safety
|
|
179
165
|
|
|
180
|
-
|
|
181
|
-
|----------|----------------------|
|
|
182
|
-
| **Novice** | High Security, high Conformity, low Self-Direction |
|
|
183
|
-
| **Professional** | High Achievement, high Competence, high Self-Direction |
|
|
184
|
-
| **Elderly** | High Tradition, high Security, moderate Benevolence |
|
|
185
|
-
| **Accessibility** | High Universalism, variable by specific disability |
|
|
166
|
+
AI agents need boundaries. CBrowser classifies every action by risk level:
|
|
186
167
|
|
|
187
|
-
|
|
168
|
+
| Zone | Examples | Behavior |
|
|
169
|
+
|------|----------|----------|
|
|
170
|
+
| 🟢 **Green** | Navigate, read, screenshot | Auto-execute |
|
|
171
|
+
| 🟡 **Yellow** | Click buttons, fill forms | Log and proceed |
|
|
172
|
+
| 🔴 **Red** | Submit, delete, purchase | Requires verification |
|
|
173
|
+
| ⬛ **Black** | Bypass auth, inject scripts | Never executes |
|
|
188
174
|
|
|
189
175
|
---
|
|
190
176
|
|
|
191
|
-
##
|
|
177
|
+
## Site Knowledge System
|
|
178
|
+
|
|
179
|
+
CBrowser learns your site over time:
|
|
180
|
+
|
|
181
|
+
- **Page Understanding** — DOM analysis, page type classification, available affordances
|
|
182
|
+
- **Site Model Learning** — Persistent knowledge graph across sessions
|
|
183
|
+
- **Cross-Session Profiles** — AES-256-GCM encrypted cookie/state profiles
|
|
184
|
+
- **Goal Decomposition** — Sub-goal trees with fallback strategies
|
|
192
185
|
|
|
193
|
-
|
|
186
|
+
---
|
|
187
|
+
|
|
188
|
+
## Natural Language Testing
|
|
194
189
|
|
|
195
190
|
```txt
|
|
196
191
|
# Test: Checkout Flow
|
|
@@ -205,38 +200,24 @@ verify url contains "/confirmation"
|
|
|
205
200
|
|
|
206
201
|
```bash
|
|
207
202
|
npx cbrowser test-suite checkout-test.txt --html
|
|
208
|
-
```
|
|
209
|
-
|
|
210
|
-
### Self-Healing Test Repair
|
|
211
203
|
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
```bash
|
|
204
|
+
# Auto-repair broken tests
|
|
215
205
|
npx cbrowser repair-tests broken-test.txt --auto-apply --verify
|
|
216
206
|
```
|
|
217
207
|
|
|
218
|
-
CBrowser analyzes failures, generates alternative selectors, and repairs tests automatically.
|
|
219
|
-
|
|
220
208
|
---
|
|
221
209
|
|
|
222
|
-
## Visual Testing
|
|
223
|
-
|
|
224
|
-
### AI Visual Regression
|
|
225
|
-
|
|
226
|
-
Semantic comparison—understands what changed, not just pixel differences:
|
|
210
|
+
## Visual Testing
|
|
227
211
|
|
|
228
212
|
```bash
|
|
213
|
+
# AI visual regression
|
|
229
214
|
npx cbrowser ai-visual capture "https://your-site.com" --name homepage
|
|
230
215
|
npx cbrowser ai-visual test "https://staging.your-site.com" homepage --html
|
|
231
|
-
```
|
|
232
|
-
|
|
233
|
-
### Cross-Browser & Responsive
|
|
234
216
|
|
|
235
|
-
|
|
236
|
-
# Compare Chrome, Firefox, Safari rendering
|
|
217
|
+
# Cross-browser (Chrome, Firefox, Safari)
|
|
237
218
|
npx cbrowser cross-browser "https://your-site.com" --html
|
|
238
219
|
|
|
239
|
-
#
|
|
220
|
+
# Responsive (mobile, tablet, desktop)
|
|
240
221
|
npx cbrowser responsive "https://your-site.com" --html
|
|
241
222
|
|
|
242
223
|
# A/B comparison (staging vs production)
|
|
@@ -245,88 +226,23 @@ npx cbrowser ab "https://staging.your-site.com" "https://your-site.com" --html
|
|
|
245
226
|
|
|
246
227
|
---
|
|
247
228
|
|
|
248
|
-
##
|
|
249
|
-
|
|
250
|
-
The 6-layer Sequential Transport Chain models how cognitive effort flows through perception, processing, and action:
|
|
251
|
-
|
|
252
|
-
| Layer | What It Measures | Research Basis |
|
|
253
|
-
|-------|-----------------|----------------|
|
|
254
|
-
| **Saliency** | Visual attention capture | CIE-Lab W₂ perceptual model |
|
|
255
|
-
| **Cognitive Load** | Information processing demand | Sweller (1988) CLT |
|
|
256
|
-
| **Decision** | Choice complexity and fatigue | Hick-Hyman Law |
|
|
257
|
-
| **Motor** | Physical interaction difficulty | Grossman & Balakrishnan (2005) |
|
|
258
|
-
| **Frustration** | Emotional cost accumulation | Ceaparu et al. (2004) |
|
|
259
|
-
| **Readability** | Text comprehension effort | Perry & Zorzi (2013) reading model |
|
|
260
|
-
|
|
261
|
-
```bash
|
|
262
|
-
# Compute total cognitive effort for a persona on any URL
|
|
263
|
-
npx cbrowser cognitive-effort --url "https://your-site.com" --persona first-timer
|
|
264
|
-
```
|
|
265
|
-
|
|
266
|
-
Returns: total CTC score, per-layer breakdown, bottleneck identification, abandonment risk percentage, and motor accessibility overlay.
|
|
267
|
-
|
|
268
|
-
---
|
|
269
|
-
|
|
270
|
-
## Visual Overlays & Attention Analysis (v18.35.0)
|
|
271
|
-
|
|
272
|
-
Generate visual cognitive narratives showing where users look, what they struggle with, and whether CTAs capture attention:
|
|
273
|
-
|
|
274
|
-
```bash
|
|
275
|
-
# Full visual cognitive story — generates 4 annotated images + narrative
|
|
276
|
-
npx cbrowser visual-cognitive-story --url "https://your-site.com" --persona cognitive-adhd
|
|
277
|
-
|
|
278
|
-
# Attention heatmap — where does this persona look?
|
|
279
|
-
npx cbrowser attention-analysis --url "https://your-site.com" --persona first-timer
|
|
280
|
-
```
|
|
281
|
-
|
|
282
|
-
**Overlays generated:**
|
|
283
|
-
- **Attention heatmap** — CIE-Lab saliency on grayscale base (red = high attention)
|
|
284
|
-
- **Motor accessibility** — Green/yellow/red per element by P(hit)
|
|
285
|
-
- **Attention quality** — CTAs green, distractors red, headings blue
|
|
286
|
-
- **Comparison diff** — Blue = persona A attention, red = persona B
|
|
287
|
-
|
|
288
|
-
**Metrics returned:** CTA capture rate, value prop salience, distractor ratio, quality score (0-100), entropy.
|
|
289
|
-
|
|
290
|
-
---
|
|
291
|
-
|
|
292
|
-
## Site Knowledge System (v18.30.0)
|
|
293
|
-
|
|
294
|
-
CBrowser learns your site over time for smarter navigation:
|
|
229
|
+
## Competitive UX Benchmark
|
|
295
230
|
|
|
296
|
-
|
|
297
|
-
- **Site Model Learning** — Persistent knowledge graph across sessions
|
|
298
|
-
- **Cross-Session Profiles** — AES-256-GCM encrypted cookie/state profiles
|
|
299
|
-
- **Goal Decomposition** — Sub-goal trees with fallback strategies
|
|
300
|
-
|
|
301
|
-
```bash
|
|
302
|
-
# Check what CBrowser knows about a site
|
|
303
|
-
npx cbrowser site-model-status
|
|
304
|
-
```
|
|
305
|
-
|
|
306
|
-
---
|
|
307
|
-
|
|
308
|
-
## AI Friendliness Suite (v18.20.0)
|
|
309
|
-
|
|
310
|
-
Five tools to make your site ready for the AI agent era:
|
|
311
|
-
|
|
312
|
-
| Tool | What It Does |
|
|
313
|
-
|------|-------------|
|
|
314
|
-
| `agent_ready_audit` | Score site on findability, stability, accessibility, semantics (A-F grade) |
|
|
315
|
-
| `ai_benchmark` | Compare AI-friendliness across competitor URLs |
|
|
316
|
-
| `webmcp_ready_audit` | Audit MCP server for WebMCP compatibility |
|
|
317
|
-
| `remediation_patches` | Generate actionable code fixes for audit findings |
|
|
318
|
-
| `llms_txt_generate` | Generate AI-readable llms.txt site description |
|
|
231
|
+
Run identical cognitive journeys across your site and competitors:
|
|
319
232
|
|
|
320
233
|
```bash
|
|
321
|
-
npx cbrowser
|
|
322
|
-
|
|
234
|
+
npx cbrowser competitive-benchmark \
|
|
235
|
+
--sites "https://your-site.com,https://competitor-a.com,https://competitor-b.com" \
|
|
236
|
+
--goal "sign up for free trial" \
|
|
237
|
+
--persona first-timer \
|
|
238
|
+
--html
|
|
323
239
|
```
|
|
324
240
|
|
|
325
241
|
---
|
|
326
242
|
|
|
327
|
-
## Geo Proxy
|
|
243
|
+
## Geo Proxy
|
|
328
244
|
|
|
329
|
-
Test from 12 global regions via residential proxies
|
|
245
|
+
Test from 12 global regions via residential proxies:
|
|
330
246
|
|
|
331
247
|
```bash
|
|
332
248
|
npx cbrowser cognitive-journey \
|
|
@@ -336,49 +252,7 @@ npx cbrowser cognitive-journey \
|
|
|
336
252
|
--geo-region uk
|
|
337
253
|
```
|
|
338
254
|
|
|
339
|
-
**
|
|
340
|
-
|
|
341
|
-
---
|
|
342
|
-
|
|
343
|
-
## UX Analysis Suite
|
|
344
|
-
|
|
345
|
-
### Agent-Ready Audit
|
|
346
|
-
|
|
347
|
-
Analyze any website for AI-agent friendliness:
|
|
348
|
-
|
|
349
|
-
```bash
|
|
350
|
-
npx cbrowser agent-ready-audit "https://your-site.com" --html
|
|
351
|
-
```
|
|
352
|
-
|
|
353
|
-
Returns:
|
|
354
|
-
- **Findability score** — Can agents locate elements? (ARIA labels, semantic HTML)
|
|
355
|
-
- **Stability score** — Will selectors break? (hidden inputs, overlays)
|
|
356
|
-
- **Letter grade (A-F)** with prioritized remediation and code examples
|
|
357
|
-
|
|
358
|
-
### Competitive UX Benchmark
|
|
359
|
-
|
|
360
|
-
Run identical cognitive journeys across your site and competitors:
|
|
361
|
-
|
|
362
|
-
```bash
|
|
363
|
-
npx cbrowser competitive-benchmark \
|
|
364
|
-
--sites "https://your-site.com,https://competitor-a.com,https://competitor-b.com" \
|
|
365
|
-
--goal "sign up for free trial" \
|
|
366
|
-
--persona first-timer \
|
|
367
|
-
--html
|
|
368
|
-
```
|
|
369
|
-
|
|
370
|
-
### Accessibility Empathy Mode
|
|
371
|
-
|
|
372
|
-
Simulate how users with disabilities experience your site:
|
|
373
|
-
|
|
374
|
-
```bash
|
|
375
|
-
npx cbrowser empathy-audit "https://your-site.com" \
|
|
376
|
-
--goal "complete signup" \
|
|
377
|
-
--disabilities "motor-tremor,low-vision,adhd" \
|
|
378
|
-
--html
|
|
379
|
-
```
|
|
380
|
-
|
|
381
|
-
**Available personas (11 accessibility):** `motor-impairment-tremor`, `low-vision-magnified`, `cognitive-adhd`, `dyslexic-user`, `deaf-user`, `elderly-low-vision`, `color-blind-deuteranopia`, `autism-spectrum`, `intellectual-disability`, `aphasia-receptive`, `dyscalculia`
|
|
255
|
+
**Regions:** `us-west`, `us-east`, `us-central`, `uk`, `germany`, `france`, `japan`, `australia`, `brazil`, `india`, `canada`, `singapore`
|
|
382
256
|
|
|
383
257
|
---
|
|
384
258
|
|
|
@@ -388,15 +262,13 @@ CBrowser runs as an MCP server for Claude Desktop and claude.ai.
|
|
|
388
262
|
|
|
389
263
|
### Remote MCP (claude.ai)
|
|
390
264
|
|
|
391
|
-
**Public Demo Server** (rate-limited
|
|
265
|
+
**Public Demo Server** (rate-limited):
|
|
392
266
|
```
|
|
393
267
|
https://demo.cbrowser.ai/mcp
|
|
394
268
|
```
|
|
395
269
|
|
|
396
270
|
Deploy your own: see [Remote MCP Server Guide](https://cbrowser.ai/docs/Remote-MCP-Server)
|
|
397
271
|
|
|
398
|
-
**v18.13.0+:** Screenshots automatically compress to JPEG in remote mode to stay under claude.ai's 200KB tool response limit. Compression is adaptive (quality 85→25, scales down if needed).
|
|
399
|
-
|
|
400
272
|
### Local MCP (Claude Desktop)
|
|
401
273
|
|
|
402
274
|
```json
|
|
@@ -432,6 +304,29 @@ Deploy your own: see [Remote MCP Server Guide](https://cbrowser.ai/docs/Remote-M
|
|
|
432
304
|
| **Session & Browser** | `save_session`, `load_session`, `delete_session`, `list_sessions`, `list_baselines`, `browser_health`, `browser_recover`, `reset_browser`, `heal_stats`, `status` | 10 |
|
|
433
305
|
| **Utility** | `assert`, `ask_user`, `set_api_key`, `api_key_status`, `clear_api_key`, `get_api_key_prompt` | 6 |
|
|
434
306
|
|
|
307
|
+
### Token Cost & Selective Loading
|
|
308
|
+
|
|
309
|
+
108 MCP tools consume ~45,000 tokens in LLM context. For cost-sensitive use, load selectively:
|
|
310
|
+
|
|
311
|
+
```typescript
|
|
312
|
+
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
313
|
+
import {
|
|
314
|
+
registerNavigationTools,
|
|
315
|
+
registerInteractionTools,
|
|
316
|
+
registerExtractionTools,
|
|
317
|
+
} from "cbrowser/mcp-tools";
|
|
318
|
+
|
|
319
|
+
const server = new McpServer({ name: "my-app", version: "1.0.0" });
|
|
320
|
+
const context = { getBrowser: () => browser };
|
|
321
|
+
|
|
322
|
+
// ~5,000 tokens instead of ~45,000
|
|
323
|
+
registerNavigationTools(server, context);
|
|
324
|
+
registerInteractionTools(server, context);
|
|
325
|
+
registerExtractionTools(server, context);
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
**Categories:** `navigation`, `interaction`, `extraction`, `assertion`, `analysis`, `session`, `healing`, `visualTesting`, `testing`, `bugAnalysis`, `personaComparison`, `cognitive`, `cognitiveTransport`, `attention`, `siteKnowledge`, `values`, `performance`, `audit`, `browserManagement`, `security`, `marketing`, `remediation`, `llmsTxt`.
|
|
329
|
+
|
|
435
330
|
---
|
|
436
331
|
|
|
437
332
|
## CI/CD Integration
|
|
@@ -462,20 +357,6 @@ docker run --rm -v $(pwd)/tests:/work/tests ghcr.io/alexandriashai/cbrowser:late
|
|
|
462
357
|
|
|
463
358
|
---
|
|
464
359
|
|
|
465
|
-
## Modular Architecture
|
|
466
|
-
|
|
467
|
-
Tree-shakeable imports for minimal bundle size:
|
|
468
|
-
|
|
469
|
-
```typescript
|
|
470
|
-
// Import specific modules
|
|
471
|
-
import { runVisualRegression, runCrossBrowserTest } from 'cbrowser/visual';
|
|
472
|
-
import { runNLTestSuite, detectFlakyTests, repairTest } from 'cbrowser/testing';
|
|
473
|
-
import { huntBugs, runChaosTest, findElementByIntent } from 'cbrowser/analysis';
|
|
474
|
-
import { capturePerformanceBaseline, detectPerformanceRegression } from 'cbrowser/performance';
|
|
475
|
-
```
|
|
476
|
-
|
|
477
|
-
---
|
|
478
|
-
|
|
479
360
|
## API Reference
|
|
480
361
|
|
|
481
362
|
```typescript
|
|
@@ -483,14 +364,14 @@ import { CBrowser } from 'cbrowser';
|
|
|
483
364
|
|
|
484
365
|
const browser = new CBrowser({
|
|
485
366
|
headless: true,
|
|
486
|
-
persistent: true,
|
|
367
|
+
persistent: true,
|
|
487
368
|
});
|
|
488
369
|
|
|
489
370
|
await browser.navigate('https://example.com');
|
|
490
371
|
|
|
491
372
|
const result = await browser.smartClick('Sign In', {
|
|
492
373
|
maxRetries: 3,
|
|
493
|
-
minConfidence: 0.8
|
|
374
|
+
minConfidence: 0.8,
|
|
494
375
|
});
|
|
495
376
|
|
|
496
377
|
const assertion = await browser.assert("page contains 'Welcome'");
|
|
@@ -501,137 +382,71 @@ if (!assertion.passed) {
|
|
|
501
382
|
await browser.close();
|
|
502
383
|
```
|
|
503
384
|
|
|
385
|
+
### Modular Imports
|
|
386
|
+
|
|
387
|
+
```typescript
|
|
388
|
+
import { runVisualRegression, runCrossBrowserTest } from 'cbrowser/visual';
|
|
389
|
+
import { runNLTestSuite, detectFlakyTests, repairTest } from 'cbrowser/testing';
|
|
390
|
+
import { huntBugs, runChaosTest, findElementByIntent } from 'cbrowser/analysis';
|
|
391
|
+
import { capturePerformanceBaseline, detectPerformanceRegression } from 'cbrowser/performance';
|
|
392
|
+
```
|
|
393
|
+
|
|
504
394
|
---
|
|
505
395
|
|
|
506
396
|
## Configuration
|
|
507
397
|
|
|
508
|
-
### Environment Variables
|
|
509
|
-
|
|
510
398
|
| Variable | Default | Description |
|
|
511
399
|
|----------|---------|-------------|
|
|
512
400
|
| `CBROWSER_DATA_DIR` | `~/.cbrowser` | Data storage directory |
|
|
513
401
|
| `CBROWSER_HEADLESS` | `true` | Run headless |
|
|
514
402
|
| `CBROWSER_BROWSER` | `chromium` | Browser engine |
|
|
515
403
|
| `CBROWSER_TIMEOUT` | `30000` | Default timeout (ms) |
|
|
516
|
-
| `CBROWSER_PROXY` | — | Proxy URL
|
|
517
|
-
| `CBROWSER_PROXY_SERVER` | — | Proxy server (alternative to full URL) |
|
|
518
|
-
| `CBROWSER_PROXY_USERNAME` | — | Proxy username (with `CBROWSER_PROXY_SERVER`) |
|
|
519
|
-
| `CBROWSER_PROXY_PASSWORD` | — | Proxy password (with `CBROWSER_PROXY_SERVER`) |
|
|
520
|
-
|
|
521
|
-
### API Key (for Cognitive Journeys)
|
|
404
|
+
| `CBROWSER_PROXY` | — | Proxy URL |
|
|
522
405
|
|
|
523
406
|
```bash
|
|
524
|
-
npx cbrowser config set-api-key
|
|
407
|
+
npx cbrowser config set-api-key # Required for cognitive journeys
|
|
525
408
|
```
|
|
526
409
|
|
|
527
|
-
### Token Cost & Selective Loading
|
|
528
|
-
|
|
529
|
-
CBrowser's 108 MCP tools consume approximately **~45,000 tokens** when loaded into an LLM context. For cost-sensitive applications, use selective tool loading:
|
|
530
|
-
|
|
531
|
-
**Tool Categories (for programmatic use):**
|
|
532
|
-
|
|
533
|
-
| Category | Tools | Use Case |
|
|
534
|
-
|----------|-------|----------|
|
|
535
|
-
| `navigation` | navigate, screenshot, scroll | Basic browsing |
|
|
536
|
-
| `interaction` | click, fill, smart_click | Form automation |
|
|
537
|
-
| `extraction` | extract, analyze_page | Data scraping |
|
|
538
|
-
| `assertion` | assert | Testing validation |
|
|
539
|
-
| `accessibility` | empathy_audit, hunt_bugs | A11y testing |
|
|
540
|
-
| `cognitive` | cognitive_journey_* | User simulation |
|
|
541
|
-
| `visual` | visual_baseline, visual_regression | Visual testing |
|
|
542
|
-
| `performance` | perf_baseline, perf_regression | Performance monitoring |
|
|
543
|
-
| `session` | save_session, load_session | State management |
|
|
544
|
-
|
|
545
|
-
**Programmatic selective loading:**
|
|
546
|
-
|
|
547
|
-
```typescript
|
|
548
|
-
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
549
|
-
import {
|
|
550
|
-
registerNavigationTools,
|
|
551
|
-
registerInteractionTools,
|
|
552
|
-
registerExtractionTools,
|
|
553
|
-
} from "cbrowser/mcp-tools";
|
|
554
|
-
|
|
555
|
-
const server = new McpServer({ name: "my-app", version: "1.0.0" });
|
|
556
|
-
const context = { getBrowser: () => browser };
|
|
557
|
-
|
|
558
|
-
// Only load what you need (~5,000 tokens instead of ~38,000)
|
|
559
|
-
registerNavigationTools(server, context);
|
|
560
|
-
registerInteractionTools(server, context);
|
|
561
|
-
registerExtractionTools(server, context);
|
|
562
|
-
```
|
|
563
|
-
|
|
564
|
-
**Full category list:** `navigation`, `interaction`, `extraction`, `assertion`, `analysis`, `session`, `healing`, `visualTesting`, `testing`, `bugAnalysis`, `personaComparison`, `cognitive`, `values`, `performance`, `audit`, `browserManagement`, `security`, `marketing`, `remediation`, `llmsTxt`.
|
|
565
|
-
|
|
566
|
-
---
|
|
567
|
-
|
|
568
|
-
## Examples
|
|
569
|
-
|
|
570
|
-
| Example | Description |
|
|
571
|
-
|---------|-------------|
|
|
572
|
-
| [`examples/basic-usage.ts`](examples/basic-usage.ts) | Navigation, extraction, sessions |
|
|
573
|
-
| [`examples/cognitive-journey.ts`](examples/cognitive-journey.ts) | Cognitive simulation with personas |
|
|
574
|
-
| [`examples/visual-testing.ts`](examples/visual-testing.ts) | Visual regression, cross-browser, A/B |
|
|
575
|
-
| [`examples/workflows/`](examples/workflows/) | E2E recipes for common scenarios |
|
|
576
|
-
| [`examples/ci-cd/`](examples/ci-cd/) | GitHub Actions, GitLab CI setup |
|
|
577
|
-
|
|
578
410
|
---
|
|
579
411
|
|
|
580
412
|
## Enterprise Edition
|
|
581
413
|
|
|
582
|
-
[CBrowser Enterprise](https://
|
|
414
|
+
[CBrowser Enterprise](https://cbrowser.ai/enterprise) adds:
|
|
583
415
|
|
|
584
416
|
| Feature | Description |
|
|
585
417
|
|---------|-------------|
|
|
586
|
-
| **Marketing Suite** |
|
|
418
|
+
| **Marketing Suite** | Test which design/copy/UX patterns influence which buyer segments |
|
|
587
419
|
| **8 Marketing Personas** | B2B (enterprise-buyer, startup-founder, procurement-manager, technical-evaluator) + Consumer (impulse-shopper, price-researcher, loyal-customer, skeptical-first-timer) |
|
|
588
420
|
| **Influence Matrix** | Conversion effectiveness for variant × persona combinations |
|
|
589
421
|
| **Lever Analysis** | Which psychological persuasion patterns work for each persona |
|
|
590
422
|
| **Constitutional Stealth** | Full stealth measures for authorized penetration testing |
|
|
423
|
+
| **Web Security Scan** | OWASP-based security scanning |
|
|
591
424
|
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
```bash
|
|
595
|
-
# Start Enterprise MCP server
|
|
596
|
-
npx cbrowser-enterprise mcp-server
|
|
597
|
-
|
|
598
|
-
# List marketing personas
|
|
599
|
-
npx cbrowser-enterprise marketing personas list --category b2b
|
|
600
|
-
```
|
|
601
|
-
|
|
602
|
-
See [Marketing Suite Wiki](https://github.com/alexandriashai/cbrowser/wiki/Marketing-Suite) for full documentation.
|
|
425
|
+
All 108 MCP tools included with no rate limits.
|
|
603
426
|
|
|
604
427
|
---
|
|
605
428
|
|
|
606
429
|
## License
|
|
607
430
|
|
|
608
|
-
**MIT License** — Free and open source.
|
|
609
|
-
|
|
610
|
-
Use, modify, and distribute freely for any purpose, including commercial and production use. See [LICENSE](LICENSE) for full terms.
|
|
431
|
+
**MIT License** — Free and open source. See [LICENSE](LICENSE).
|
|
611
432
|
|
|
612
433
|
---
|
|
613
434
|
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
© 2026 Alexandria Eden
|
|
617
|
-
|
|
618
|
-
Contact: [alexandria.shai.eden@gmail.com](mailto:alexandria.shai.eden@gmail.com)
|
|
619
|
-
Website: [cbrowser.ai](https://cbrowser.ai)
|
|
435
|
+
© 2026 Alexandria Eden · [cbrowser.ai](https://cbrowser.ai) · [alexandria.shai.eden@gmail.com](mailto:alexandria.shai.eden@gmail.com)
|
|
620
436
|
|
|
621
437
|
---
|
|
622
438
|
|
|
623
439
|
## Links
|
|
624
440
|
|
|
625
|
-
- **[
|
|
441
|
+
- **[Documentation](https://cbrowser.ai/docs)** — Full docs, guides, API reference
|
|
626
442
|
- [NPM Package](https://www.npmjs.com/package/cbrowser)
|
|
627
|
-
- [GitHub
|
|
443
|
+
- [GitHub](https://github.com/alexandriashai/cbrowser)
|
|
628
444
|
- [Issue Tracker](https://github.com/alexandriashai/cbrowser/issues)
|
|
629
|
-
- [A+ Assessment Report](https://claude.ai/public/artifacts/0cee560d-60b8-44d6-8eec-e674fbfac9c4)
|
|
630
445
|
- [Roadmap](https://cbrowser.ai/docs/Roadmap)
|
|
631
446
|
|
|
632
|
-
### Research
|
|
447
|
+
### Research
|
|
633
448
|
|
|
634
449
|
- [Research Methodology](https://cbrowser.ai/docs/Research-Methodology) — How 26 traits were selected and validated
|
|
635
450
|
- [Trait Index](https://cbrowser.ai/docs/Trait-Index) — All cognitive traits with citations
|
|
636
|
-
- [Bibliography](https://cbrowser.ai/docs/Bibliography) —
|
|
451
|
+
- [Bibliography](https://cbrowser.ai/docs/Bibliography) — Academic references
|
|
637
452
|
- [Persona Index](https://cbrowser.ai/docs/Persona-Index) — All 17 cognitive + 8 marketing personas
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "cbrowser",
|
|
3
|
-
"version": "18.42.
|
|
3
|
+
"version": "18.42.7",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Cognitive browser automation that thinks like your users—and helps AI agents navigate too. Simulate real user cognition with abandonment detection, constitutional safety, chaos engineering, and UX friction discovery. Sites that pass CBrowser's cognitive tests are easier for both humans and AI agents to navigate.",
|
|
6
6
|
"main": "dist/index.js",
|