cbrowser 18.63.0 → 18.63.2
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/package.json +1 -1
- package/docs/ASSESSMENT.md +0 -132
- package/docs/AUTH0-SETUP.md +0 -207
- package/docs/COGNITIVE-OPTIMAL-TRANSPORT-RESEARCH.md +0 -238
- package/docs/DEMO-DEPLOYMENT.md +0 -177
- package/docs/ENTERPRISE-INTEGRATION.md +0 -250
- package/docs/GETTING-STARTED.md +0 -232
- package/docs/INSTALL.md +0 -274
- package/docs/MCP-INTEGRATION.md +0 -301
- package/docs/METHODOLOGY.md +0 -276
- package/docs/PERSONA-QUESTIONNAIRE.md +0 -328
- package/docs/README.md +0 -45
- package/docs/REMOTE-MCP-SERVER.md +0 -569
- package/docs/SECURITY_WHITEPAPER.md +0 -475
- package/docs/STRESS-TEST-v16.14.4.md +0 -241
- package/docs/Tool-Cognitive-Journey-Autonomous.md +0 -270
- package/docs/Tool-Competitive-Benchmark.md +0 -293
- package/docs/Tool-Empathy-Audit.md +0 -331
- package/docs/Tool-Hunt-Bugs.md +0 -305
- package/docs/Tool-Marketing-Campaign.md +0 -298
- package/docs/Tool-Persona-Create.md +0 -274
- package/docs/Tools-Accessibility.md +0 -208
- package/docs/Tools-Browser-Automation.md +0 -311
- package/docs/Tools-Cognitive-Journeys.md +0 -233
- package/docs/Tools-Marketing-Intelligence.md +0 -271
- package/docs/Tools-Overview.md +0 -162
- package/docs/Tools-Persona-System.md +0 -300
- package/docs/Tools-Session-State.md +0 -278
- package/docs/Tools-Testing-Quality.md +0 -257
- package/docs/Tools-Utilities.md +0 -182
- package/docs/Tools-Visual-Performance.md +0 -278
- package/docs/hunt-bugs-coverage.md +0 -103
- package/docs/personas/Persona-ADHD.md +0 -141
- package/docs/personas/Persona-ElderlyUser.md +0 -137
- package/docs/personas/Persona-FirstTimer.md +0 -137
- package/docs/personas/Persona-ImpatientUser.md +0 -138
- package/docs/personas/Persona-Index.md +0 -302
- package/docs/personas/Persona-LowVision.md +0 -139
- package/docs/personas/Persona-MobileUser.md +0 -139
- package/docs/personas/Persona-MotorTremor.md +0 -139
- package/docs/personas/Persona-PowerUser.md +0 -135
- package/docs/personas/Persona-ScreenReaderUser.md +0 -139
- package/docs/research/Bibliography.md +0 -275
- package/docs/research/Research-Methodology.md +0 -244
- package/docs/research/Values-Research.md +0 -432
- package/docs/traits/Trait-AnchoringBias.md +0 -227
- package/docs/traits/Trait-AttributionStyle.md +0 -280
- package/docs/traits/Trait-AuthoritySensitivity.md +0 -141
- package/docs/traits/Trait-ChangeBlindness.md +0 -171
- package/docs/traits/Trait-Comprehension.md +0 -180
- package/docs/traits/Trait-Curiosity.md +0 -189
- package/docs/traits/Trait-EmotionalContagion.md +0 -144
- package/docs/traits/Trait-FOMO.md +0 -150
- package/docs/traits/Trait-Index.md +0 -166
- package/docs/traits/Trait-InformationForaging.md +0 -217
- package/docs/traits/Trait-InterruptRecovery.md +0 -249
- package/docs/traits/Trait-MentalModelRigidity.md +0 -228
- package/docs/traits/Trait-MetacognitivePlanning.md +0 -164
- package/docs/traits/Trait-Patience.md +0 -137
- package/docs/traits/Trait-Persistence.md +0 -165
- package/docs/traits/Trait-ProceduralFluency.md +0 -205
- package/docs/traits/Trait-ReadingTendency.md +0 -216
- package/docs/traits/Trait-Resilience.md +0 -162
- package/docs/traits/Trait-RiskTolerance.md +0 -162
- package/docs/traits/Trait-Satisficing.md +0 -181
- package/docs/traits/Trait-SelfEfficacy.md +0 -199
- package/docs/traits/Trait-SocialProofSensitivity.md +0 -155
- package/docs/traits/Trait-TimeHorizon.md +0 -267
- package/docs/traits/Trait-TransferLearning.md +0 -249
- package/docs/traits/Trait-TrustCalibration.md +0 -227
- package/docs/traits/Trait-WorkingMemory.md +0 -192
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "cbrowser",
|
|
3
|
-
"version": "18.63.
|
|
3
|
+
"version": "18.63.2",
|
|
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",
|
package/docs/ASSESSMENT.md
DELETED
|
@@ -1,132 +0,0 @@
|
|
|
1
|
-
> **This documentation is no longer maintained here.**
|
|
2
|
-
>
|
|
3
|
-
> For the latest version, please visit: **[CBrowser v12.0.0 - Independent Assessment](https://cbrowser.ai/docs/ASSESSMENT)**
|
|
4
|
-
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
# CBrowser v12.0.0 — Independent Assessment
|
|
8
|
-
|
|
9
|
-
**Final Grade: A**
|
|
10
|
-
|
|
11
|
-
After 360+ tool invocations across 6 rounds of rigorous stress testing, CBrowser v12.0.0 earned a Grade A assessment.
|
|
12
|
-
|
|
13
|
-
---
|
|
14
|
-
|
|
15
|
-
## Summary
|
|
16
|
-
|
|
17
|
-
| Metric | Result |
|
|
18
|
-
|--------|--------|
|
|
19
|
-
| **Issues Tracked** | 17 |
|
|
20
|
-
| **Issues Fixed** | 17 (100%) |
|
|
21
|
-
| **Regressions** | 0 |
|
|
22
|
-
| **Tools Tested** | 34 |
|
|
23
|
-
| **Tools Graded A- or Above** | 31 (91%) |
|
|
24
|
-
| **Tools Graded B+** | 3 (9%) |
|
|
25
|
-
| **Tools Below B+** | 0 |
|
|
26
|
-
|
|
27
|
-
---
|
|
28
|
-
|
|
29
|
-
## Version Journey
|
|
30
|
-
|
|
31
|
-
| Version | Grade | Key Changes |
|
|
32
|
-
|---------|-------|-------------|
|
|
33
|
-
| 11.5.0 | B+ | Baseline—intent matching broken, fill unreliable |
|
|
34
|
-
| 11.7.0 | B | Stability regressions (crashes, extract broken) |
|
|
35
|
-
| 11.10.3 | A- | All critical bugs fixed, stability restored |
|
|
36
|
-
| 11.10.4 | A | Intent buttons, smart_click gating, AB comparison |
|
|
37
|
-
| 11.10.5 | A | Stability patch, no regressions |
|
|
38
|
-
| 11.10.6 | A | Empathy audit dedup + goalAchieved calibration |
|
|
39
|
-
| **12.0.0** | **A** | License update, copyright headers, polish |
|
|
40
|
-
|
|
41
|
-
---
|
|
42
|
-
|
|
43
|
-
## Best-in-Class Capabilities
|
|
44
|
-
|
|
45
|
-
### Natural Language Test Runner ⭐
|
|
46
|
-
|
|
47
|
-
The single best natural-language browser testing tool available. 10-step E2E flows run 100% stable across 5 consecutive runs with step-level metrics.
|
|
48
|
-
|
|
49
|
-
### Fill Tool Turnaround
|
|
50
|
-
|
|
51
|
-
From fundamentally broken to handling 12-input forms by name, label, and CSS without a single failure. Complete transformation.
|
|
52
|
-
|
|
53
|
-
### Performance Baseline System
|
|
54
|
-
|
|
55
|
-
Dual-threshold noise handling with 3-run averaging. Better than what most teams build in-house.
|
|
56
|
-
|
|
57
|
-
---
|
|
58
|
-
|
|
59
|
-
## Novel & Defensible Features
|
|
60
|
-
|
|
61
|
-
No competing tool in the Playwright/Selenium/Cypress ecosystem offers this combination:
|
|
62
|
-
|
|
63
|
-
1. **Cognitive Persona Simulation** — 12 research-backed traits model human behavior
|
|
64
|
-
2. **Empathy Accessibility Audits** — Experience sites as users with disabilities
|
|
65
|
-
3. **Agent-Ready Audits** — Score any site for AI-agent friendliness
|
|
66
|
-
4. **Self-Healing Selectors with Confidence Gating** — 0.8+ threshold prevents false positives
|
|
67
|
-
5. **Constitutional AI Safety** — Risk-classified actions with verification gates
|
|
68
|
-
|
|
69
|
-
---
|
|
70
|
-
|
|
71
|
-
## Tool-by-Tool Scores
|
|
72
|
-
|
|
73
|
-
| Tool | Grade | Notes |
|
|
74
|
-
|------|-------|-------|
|
|
75
|
-
| navigate | A | Fast, reliable, correct context |
|
|
76
|
-
| screenshot | A | Consistent |
|
|
77
|
-
| extract (all 5 modes) | A | text regression fixed |
|
|
78
|
-
| click | A | Text matching reliable |
|
|
79
|
-
| smart_click | A | Confidence gating works |
|
|
80
|
-
| fill (all modes) | A | Complete turnaround |
|
|
81
|
-
| find_element_by_intent | A- | Button heuristics work |
|
|
82
|
-
| assert (all types) | A | Real actualValues |
|
|
83
|
-
| nl_test_inline | A+ | 100% stable × 5 runs |
|
|
84
|
-
| cross_browser_diff | A- | Metrics comparison works |
|
|
85
|
-
| cross_browser_test | B+ | Sensitivity tuning needed |
|
|
86
|
-
| responsive_test | A- | Finds real issues |
|
|
87
|
-
| perf_baseline | A | Dual-threshold |
|
|
88
|
-
| perf_regression | A | Noise handling |
|
|
89
|
-
| visual_baseline | A | Clean capture |
|
|
90
|
-
| visual_regression | A | Similarity scoring |
|
|
91
|
-
| save_session | A | Clean |
|
|
92
|
-
| load_session | A | Flat response |
|
|
93
|
-
| list_sessions | A | Metadata-rich |
|
|
94
|
-
| delete_session | A | Clean |
|
|
95
|
-
| cognitive_journey_init | A | 12 traits |
|
|
96
|
-
| cognitive_journey_update_state | A- | Math is sound |
|
|
97
|
-
| list_cognitive_personas | A | 6 personas |
|
|
98
|
-
| agent_ready_audit | A- | Grammar polish needed |
|
|
99
|
-
| empathy_audit | A- | Dedup and calibration fixed |
|
|
100
|
-
| hunt_bugs | A- | Multi-page crawl |
|
|
101
|
-
| generate_tests | B+ | Needs broader patterns |
|
|
102
|
-
| repair_test | B+ | Suggests alternatives |
|
|
103
|
-
| detect_flaky_tests | A | 100% stable classification |
|
|
104
|
-
| chaos_test (offline) | A- | Cache edge case |
|
|
105
|
-
| chaos_test (latency/block) | B+ | Works, sparse output |
|
|
106
|
-
| ab_comparison | A | Structured diffs |
|
|
107
|
-
| dismiss_overlay | A | Correct reporting |
|
|
108
|
-
| analyze_page | A | Concise overview |
|
|
109
|
-
|
|
110
|
-
---
|
|
111
|
-
|
|
112
|
-
## Remaining Polish Items
|
|
113
|
-
|
|
114
|
-
Minor items for future releases (none block the A grade):
|
|
115
|
-
|
|
116
|
-
- Agent audit grammar: "10 Elements lacks" → "10 elements lack"
|
|
117
|
-
- Chaos test: add load time delta to positive results
|
|
118
|
-
- Cross-browser: sensitivity threshold tuning
|
|
119
|
-
- generate_tests: recognize dropdowns and checkboxes
|
|
120
|
-
- find_element_by_intent: synonym gap ("remove" ≠ "delete")
|
|
121
|
-
|
|
122
|
-
---
|
|
123
|
-
|
|
124
|
-
## Conclusion
|
|
125
|
-
|
|
126
|
-
> "If you're building AI agents that need to interact with websites, or if you're a QA team that wants natural language tests without writing Playwright scripts, CBrowser is ready for you. The core path is reliable, the NL interface works, and the audit tools give you insights you won't get anywhere else."
|
|
127
|
-
|
|
128
|
-
---
|
|
129
|
-
|
|
130
|
-
*Assessment completed February 8, 2026*
|
|
131
|
-
|
|
132
|
-
*© 2026 Alexandria Eden. All rights reserved.*
|
package/docs/AUTH0-SETUP.md
DELETED
|
@@ -1,207 +0,0 @@
|
|
|
1
|
-
> **This documentation is no longer maintained here.**
|
|
2
|
-
>
|
|
3
|
-
> For the latest version, please visit: **[Auth0 OAuth Setup for CBrowser MCP Server](https://cbrowser.ai/docs/AUTH0-SETUP)**
|
|
4
|
-
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
# Auth0 OAuth Setup for CBrowser MCP Server
|
|
8
|
-
|
|
9
|
-
This guide walks you through setting up Auth0 authentication for the CBrowser Remote MCP Server, enabling integration with claude.ai's custom connector feature.
|
|
10
|
-
|
|
11
|
-
## Quick Start
|
|
12
|
-
|
|
13
|
-
### 1. Create Auth0 Account
|
|
14
|
-
|
|
15
|
-
1. Go to [auth0.com](https://auth0.com) and sign up (free tier works)
|
|
16
|
-
2. Create a new tenant (e.g., `cbrowser` or use your existing tenant)
|
|
17
|
-
|
|
18
|
-
### 2. Create an API
|
|
19
|
-
|
|
20
|
-
1. Go to **Applications → APIs**
|
|
21
|
-
2. Click **+ Create API**
|
|
22
|
-
3. Configure:
|
|
23
|
-
- **Name:** `CBrowser MCP API`
|
|
24
|
-
- **Identifier:** `https://cbrowser-mcp.yourdomain.com` (your server URL)
|
|
25
|
-
- **Signing Algorithm:** RS256
|
|
26
|
-
4. Click **Create**
|
|
27
|
-
|
|
28
|
-
### 3. Create an Application (Static Registration)
|
|
29
|
-
|
|
30
|
-
For secure integration, we use static client registration:
|
|
31
|
-
|
|
32
|
-
1. Go to **Applications → Applications**
|
|
33
|
-
2. Click **+ Create Application**
|
|
34
|
-
3. Configure:
|
|
35
|
-
- **Name:** `Claude.ai MCP Client`
|
|
36
|
-
- **Type:** Regular Web Application
|
|
37
|
-
4. Click **Create**
|
|
38
|
-
5. In Settings tab, configure:
|
|
39
|
-
- **Allowed Callback URLs:**
|
|
40
|
-
```
|
|
41
|
-
https://claude.ai/api/mcp/auth_callback,
|
|
42
|
-
https://claude.com/api/mcp/auth_callback
|
|
43
|
-
```
|
|
44
|
-
- **Allowed Web Origins:** `https://claude.ai, https://claude.com`
|
|
45
|
-
6. Save Changes
|
|
46
|
-
7. Note down:
|
|
47
|
-
- **Domain** (e.g., `your-tenant.auth0.com`)
|
|
48
|
-
- **Client ID**
|
|
49
|
-
- **Client Secret**
|
|
50
|
-
|
|
51
|
-
### 4. Configure MCP Server
|
|
52
|
-
|
|
53
|
-
Add these environment variables to your systemd service:
|
|
54
|
-
|
|
55
|
-
```bash
|
|
56
|
-
sudo nano /etc/systemd/system/cbrowser-mcp.service
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
Add under `[Service]`:
|
|
60
|
-
|
|
61
|
-
```ini
|
|
62
|
-
Environment=AUTH0_DOMAIN=your-tenant.auth0.com
|
|
63
|
-
Environment=AUTH0_AUDIENCE=https://cbrowser-mcp.yourdomain.com
|
|
64
|
-
Environment=AUTH0_CLIENT_ID=your-client-id
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
Reload and restart:
|
|
68
|
-
|
|
69
|
-
```bash
|
|
70
|
-
sudo systemctl daemon-reload
|
|
71
|
-
sudo systemctl restart cbrowser-mcp
|
|
72
|
-
```
|
|
73
|
-
|
|
74
|
-
### 5. Verify Setup
|
|
75
|
-
|
|
76
|
-
```bash
|
|
77
|
-
# Check protected resource metadata
|
|
78
|
-
curl https://cbrowser-mcp.yourdomain.com/.well-known/oauth-protected-resource
|
|
79
|
-
|
|
80
|
-
# Should return:
|
|
81
|
-
{
|
|
82
|
-
"resource": "https://cbrowser-mcp.yourdomain.com",
|
|
83
|
-
"authorization_servers": ["https://your-tenant.auth0.com"],
|
|
84
|
-
"bearer_methods_supported": ["header"],
|
|
85
|
-
"scopes_supported": ["openid", "profile", "cbrowser:read", "cbrowser:write"]
|
|
86
|
-
}
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
### 6. Connect from Claude.ai
|
|
90
|
-
|
|
91
|
-
1. Go to [claude.ai](https://claude.ai)
|
|
92
|
-
2. Open **Settings → Connectors**
|
|
93
|
-
3. Click **Add custom connector**
|
|
94
|
-
4. Enter: `https://cbrowser-mcp.yourdomain.com/mcp`
|
|
95
|
-
5. Claude will:
|
|
96
|
-
- Fetch the OAuth metadata from `/.well-known/oauth-protected-resource`
|
|
97
|
-
- Redirect you to Auth0 for authentication
|
|
98
|
-
- Exchange tokens and connect
|
|
99
|
-
|
|
100
|
-
---
|
|
101
|
-
|
|
102
|
-
## Architecture
|
|
103
|
-
|
|
104
|
-
```
|
|
105
|
-
┌─────────────────┐ ┌────────────────┐ ┌─────────────────┐
|
|
106
|
-
│ Claude.ai │────▶│ Auth0 │────▶│ CBrowser MCP │
|
|
107
|
-
│ │ │ │ │ Server │
|
|
108
|
-
│ 1. Discover │ │ 2. Authorize │ │ │
|
|
109
|
-
│ OAuth metadata │ │ 3. Get token │ │ 4. Validate │
|
|
110
|
-
│ │ │ │ │ JWT │
|
|
111
|
-
└─────────────────┘ └────────────────┘ └─────────────────┘
|
|
112
|
-
```
|
|
113
|
-
|
|
114
|
-
## Flow Details
|
|
115
|
-
|
|
116
|
-
1. **Discovery**: Claude fetches `/.well-known/oauth-protected-resource` to find Auth0
|
|
117
|
-
2. **Authorization**: User is redirected to Auth0 login
|
|
118
|
-
3. **Token Exchange**: Auth0 issues JWT access token
|
|
119
|
-
4. **API Access**: Claude sends requests with `Authorization: Bearer <jwt>`
|
|
120
|
-
5. **Validation**: CBrowser validates JWT against Auth0 JWKS
|
|
121
|
-
|
|
122
|
-
---
|
|
123
|
-
|
|
124
|
-
## Environment Variables
|
|
125
|
-
|
|
126
|
-
| Variable | Required | Description |
|
|
127
|
-
|----------|----------|-------------|
|
|
128
|
-
| `AUTH0_DOMAIN` | Yes | Your Auth0 tenant domain (e.g., `your-tenant.auth0.com`) |
|
|
129
|
-
| `AUTH0_AUDIENCE` | Yes | API identifier (your server URL) |
|
|
130
|
-
| `AUTH0_CLIENT_ID` | No | Client ID for static registration info |
|
|
131
|
-
|
|
132
|
-
---
|
|
133
|
-
|
|
134
|
-
## Scopes
|
|
135
|
-
|
|
136
|
-
The server supports these OAuth scopes:
|
|
137
|
-
|
|
138
|
-
| Scope | Description |
|
|
139
|
-
|-------|-------------|
|
|
140
|
-
| `openid` | OpenID Connect authentication |
|
|
141
|
-
| `profile` | User profile information |
|
|
142
|
-
| `cbrowser:read` | Read-only access to CBrowser tools |
|
|
143
|
-
| `cbrowser:write` | Full access to CBrowser tools |
|
|
144
|
-
|
|
145
|
-
---
|
|
146
|
-
|
|
147
|
-
## Troubleshooting
|
|
148
|
-
|
|
149
|
-
### "Invalid token" errors
|
|
150
|
-
|
|
151
|
-
1. Check Auth0 domain is correct
|
|
152
|
-
2. Verify audience matches exactly (including trailing slash if needed)
|
|
153
|
-
3. Check token hasn't expired
|
|
154
|
-
|
|
155
|
-
### "OAuth not configured" response
|
|
156
|
-
|
|
157
|
-
1. Ensure `AUTH0_DOMAIN` and `AUTH0_AUDIENCE` are set
|
|
158
|
-
2. Restart the service after config changes
|
|
159
|
-
|
|
160
|
-
### Claude.ai can't connect
|
|
161
|
-
|
|
162
|
-
1. Verify callback URLs include both `claude.ai` and `claude.com`
|
|
163
|
-
2. Check CORS is working (test with browser dev tools)
|
|
164
|
-
3. Ensure `/.well-known/oauth-protected-resource` is accessible
|
|
165
|
-
|
|
166
|
-
### Rate limit errors (429)
|
|
167
|
-
|
|
168
|
-
Auth0 free tier has strict rate limits. CBrowser caches validated tokens for 30 minutes to avoid hitting these limits. If you're still seeing rate limits:
|
|
169
|
-
|
|
170
|
-
1. Upgrade to Auth0 paid tier
|
|
171
|
-
2. Reduce concurrent users
|
|
172
|
-
|
|
173
|
-
### Opaque token instead of JWT
|
|
174
|
-
|
|
175
|
-
If Auth0 returns an opaque (encrypted) token instead of a JWT, CBrowser validates it via Auth0's `/userinfo` endpoint. This works but:
|
|
176
|
-
|
|
177
|
-
1. Ensure API Identifier in Auth0 exactly matches your audience (including trailing slash)
|
|
178
|
-
2. Check the Application is authorized for the API in Auth0
|
|
179
|
-
|
|
180
|
-
---
|
|
181
|
-
|
|
182
|
-
## Security Best Practices
|
|
183
|
-
|
|
184
|
-
1. **Use static registration** - Don't enable open DCR without IP restrictions
|
|
185
|
-
2. **Restrict callback URLs** - Only allow Claude's official callbacks
|
|
186
|
-
3. **Monitor logs** - Check Auth0 logs for unauthorized access attempts
|
|
187
|
-
4. **Rotate secrets** - Periodically rotate client secrets
|
|
188
|
-
5. **Use scopes** - Implement scope-based access control for sensitive tools
|
|
189
|
-
|
|
190
|
-
---
|
|
191
|
-
|
|
192
|
-
## Dual Authentication
|
|
193
|
-
|
|
194
|
-
The server supports both API keys and OAuth simultaneously:
|
|
195
|
-
|
|
196
|
-
- **API Key**: For Claude Code CLI and programmatic access
|
|
197
|
-
- **OAuth**: For claude.ai web interface
|
|
198
|
-
|
|
199
|
-
Both can be enabled at the same time. The server checks OAuth JWT first, then falls back to API key.
|
|
200
|
-
|
|
201
|
-
---
|
|
202
|
-
|
|
203
|
-
## Related Documentation
|
|
204
|
-
|
|
205
|
-
- [Auth0 MCP Documentation](https://auth0.com/ai/docs/mcp/)
|
|
206
|
-
- [MCP Authorization Spec](https://spec.modelcontextprotocol.io/specification/architecture/transports/)
|
|
207
|
-
- [RFC 9728 - OAuth Protected Resource Metadata](https://datatracker.ietf.org/doc/html/rfc9728)
|
|
@@ -1,238 +0,0 @@
|
|
|
1
|
-
# Cognitive Optimal Transport — Research Synthesis
|
|
2
|
-
|
|
3
|
-
**Date:** 2026-04-11 (updated)
|
|
4
|
-
**Issues:** #159, #160, #161, #162, #163
|
|
5
|
-
**Sources:** 50+ papers across neuroscience, HCI, accessibility, and mathematics
|
|
6
|
-
**Research agents:** 3 parallel, 80+ targeted queries
|
|
7
|
-
|
|
8
|
-
---
|
|
9
|
-
|
|
10
|
-
## The Core Finding
|
|
11
|
-
|
|
12
|
-
**Transport cost = cognitive processing cost.** This is not metaphorical — it is empirically validated across multiple domains:
|
|
13
|
-
|
|
14
|
-
- **Taylor & Fiebach (2025)**: Wasserstein distance between letter shapes predicts EEG neural activity at <225ms (pre-attentive processing)
|
|
15
|
-
- **Aoun et al. (2023)**: EMD between spatial representations predicts hippocampal remapping effort
|
|
16
|
-
- **Galeotti et al. (2022)**: Visual cortex V1 literally performs optimal transport along Wasserstein geodesics
|
|
17
|
-
- **Dabney et al. (2020, Nature)**: The brain maintains *distributions* of expected outcomes via dopamine neurons, not point estimates
|
|
18
|
-
- **Mialon et al. (ICLR 2021)**: Attention mechanisms are mathematically equivalent to optimal transport plans
|
|
19
|
-
|
|
20
|
-
**What this means:** When a user views a web page, the cognitive effort of processing it is proportional to the Wasserstein distance between their expectation distribution and what the page presents.
|
|
21
|
-
|
|
22
|
-
---
|
|
23
|
-
|
|
24
|
-
## Six-Layer Architecture for CBrowser
|
|
25
|
-
|
|
26
|
-
### Layer 1: Saliency (Visual Attention)
|
|
27
|
-
|
|
28
|
-
**What:** Generate persona-specific saliency maps showing what each persona actually *sees* as visually prominent.
|
|
29
|
-
|
|
30
|
-
**Method:** W₂ distance on CIE-Lab multivariate normals (Klein & Frintrop 2012, DAGM). Apply persona filters before computing center-surround contrast.
|
|
31
|
-
|
|
32
|
-
**Persona differentiation:**
|
|
33
|
-
- ADHD: Lower saliency threshold for local novelty (animations capture attention), weaker global integration
|
|
34
|
-
- Low vision: Only high-contrast, large elements register
|
|
35
|
-
- Elderly: Attention concentrated on text, ignores peripheral elements
|
|
36
|
-
|
|
37
|
-
**Metric:** `W₁(persona_saliency, designer_intent_saliency)` = attention alignment score
|
|
38
|
-
|
|
39
|
-
**Papers:** Bylinskii et al. (IEEE TPAMI 2019), Klein & Frintrop (DAGM 2012), Sun & Li (JEI 2018)
|
|
40
|
-
|
|
41
|
-
### Layer 2: Cognitive Load
|
|
42
|
-
|
|
43
|
-
**What:** Measure how overwhelming the visual complexity is for each persona.
|
|
44
|
-
|
|
45
|
-
**Method:** Feature Congestion + Subband Entropy (Rosenholtz et al. 2007). Apply persona-specific capacity limits.
|
|
46
|
-
|
|
47
|
-
**Persona differentiation:**
|
|
48
|
-
- ADHD: 0.3x noise tolerance → overloads at lower complexity
|
|
49
|
-
- Dyslexic: 0.4x text processing speed → text-heavy areas impose 2.5x load
|
|
50
|
-
- Power user: 1.0x tolerance → handles complexity fine
|
|
51
|
-
|
|
52
|
-
**Metric:** Entropy-based congestion per page region, thresholded per persona capacity
|
|
53
|
-
|
|
54
|
-
**Papers:** Rosenholtz et al. (J. Vision 2007), Stickel et al. (LNCS 2010), Longo et al. (ACM Computing Surveys 2023)
|
|
55
|
-
|
|
56
|
-
### Layer 3: Decision Complexity
|
|
57
|
-
|
|
58
|
-
**What:** Predict when a persona will experience decision fatigue from too many choices.
|
|
59
|
-
|
|
60
|
-
**Method:** Information entropy per choice point. Hick-Hyman Law with persona-specific coefficients. Wasserstein distance between attention distribution and uniform distribution signals shift from exploration to anchoring.
|
|
61
|
-
|
|
62
|
-
**Persona differentiation:**
|
|
63
|
-
- ADHD: Steeper Hick-Hyman slope (2.5x penalty per additional option)
|
|
64
|
-
- Analytical personality: Flatter slope (enjoys comparison)
|
|
65
|
-
- Elderly: Lower entropy threshold before confusion
|
|
66
|
-
|
|
67
|
-
**Metric:** `W(attention_over_options, uniform_distribution)` → when this increases past persona threshold, decision fatigue is occurring
|
|
68
|
-
|
|
69
|
-
**Papers:** Plonsky et al. (Ann. Math. AI 2022), Bounded Rationality via Wasserstein (arXiv 2025), Hick-Hyman (NeuroImage 2025)
|
|
70
|
-
|
|
71
|
-
### Layer 4: Motor Accessibility
|
|
72
|
-
|
|
73
|
-
**What:** Predict how hard interactive elements are to reach and click for each persona.
|
|
74
|
-
|
|
75
|
-
**Method:** Probabilistic pointing with bivariate Gaussian endpoint distributions (Grossman & Balakrishnan 2005). Motor-impaired personas have wider, asymmetric Gaussians.
|
|
76
|
-
|
|
77
|
-
**Persona differentiation:**
|
|
78
|
-
- Motor tremor: 3x endpoint dispersion, asymmetric covariance
|
|
79
|
-
- Elderly: 1.8x dispersion
|
|
80
|
-
- Power user: Tight, circular distribution
|
|
81
|
-
|
|
82
|
-
**Metric:** `P(hit) = ∫ persona_gaussian over target_region` → elements below threshold are motor barriers
|
|
83
|
-
|
|
84
|
-
**Papers:** Grossman & Balakrishnan (ACM TOCHI 2005)
|
|
85
|
-
|
|
86
|
-
### Layer 5: Frustration & Abandonment
|
|
87
|
-
|
|
88
|
-
**What:** Predict when a persona will give up based on the gap between expected and actual experience.
|
|
89
|
-
|
|
90
|
-
**Method:** Model expected interaction distribution per task step. Compute `W(expected, actual)` during simulation. Cumulative transport cost exceeding persona tolerance → abandonment.
|
|
91
|
-
|
|
92
|
-
**Foundation:** Distributional RL (Dabney et al. 2020, Nature) — the brain maintains reward *distributions*, not point estimates. Frustration = large negative Wasserstein shift between expected and actual reward distributions.
|
|
93
|
-
|
|
94
|
-
**Persona differentiation:**
|
|
95
|
-
- Impatient user: Low tolerance threshold
|
|
96
|
-
- Resilient user: High threshold
|
|
97
|
-
- ADHD: Low threshold for temporal delays, high for novelty
|
|
98
|
-
|
|
99
|
-
**Metric:** `Σ W(expected_step_k, actual_step_k)` over task steps → predict abandonment point
|
|
100
|
-
|
|
101
|
-
**Papers:** Dabney et al. (Nature 2020), Yamauchi & Xiao (Cognitive Science 2018), Ceaparu et al. (ACM TOCHI 2023)
|
|
102
|
-
|
|
103
|
-
### Layer 6: Readability
|
|
104
|
-
|
|
105
|
-
**What:** Predict reading difficulty per text block for each persona.
|
|
106
|
-
|
|
107
|
-
**Method:** Multi-deficit model (Perry, Zorzi, Ziegler 2019) with persona-specific parameters for orthographic, phonological, and vocabulary processing. Font effects from Rello & Baeza-Yates (2016).
|
|
108
|
-
|
|
109
|
-
**Persona differentiation:**
|
|
110
|
-
- Dyslexic: 2.5x fixation duration, needs sans-serif/monospace
|
|
111
|
-
- Low vision: Needs 14px+ text, high contrast
|
|
112
|
-
- Second-language: Slower vocabulary access
|
|
113
|
-
|
|
114
|
-
**Metric:** Transport cost from persona's deficit profile to fluent-reader profile = total processing penalty per text block
|
|
115
|
-
|
|
116
|
-
**Papers:** Perry et al. (Psych. Science 2019), Rello & Baeza-Yates (ACM TACCESS 2016), Legge & Xiong (Frontiers 2021)
|
|
117
|
-
|
|
118
|
-
---
|
|
119
|
-
|
|
120
|
-
## Meta-Metric: Total Cognitive Transport Cost
|
|
121
|
-
|
|
122
|
-
The overall score for a persona on a page is the **sum of Wasserstein transport costs across all six layers** — how much extra cognitive work this persona must do compared to the designer's assumed user.
|
|
123
|
-
|
|
124
|
-
```
|
|
125
|
-
TotalCost(persona, page) = Σ_layer w_layer × W(persona_layer, baseline_layer)
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
This is a single, principled, theoretically grounded number. No competitor has anything like it.
|
|
129
|
-
|
|
130
|
-
---
|
|
131
|
-
|
|
132
|
-
## Mathematical Foundations (Implementability)
|
|
133
|
-
|
|
134
|
-
| Component | Complexity (d=26) | GPU | TypeScript Feasible | Status |
|
|
135
|
-
|---|---|---|---|---|
|
|
136
|
-
| Sliced Wasserstein distance | O(L×n×d) ~520K ops | No | Yes, sub-ms | **Shipped v18.26** |
|
|
137
|
-
| Gaussian W₂ + geodesic | O(d³) ~17.5K ops | No | Yes, sub-ms | **Shipped v18.27** |
|
|
138
|
-
| Gaussian barycenter | O(K×d³) per iter | No | Yes, sub-ms | **Shipped v18.26** |
|
|
139
|
-
| DRO adversarial personas | O(N×d) per LP | No | Yes, sub-ms | **Shipped v18.27** |
|
|
140
|
-
| Sinkhorn discrete OT | O(n²/ε²) per iter | No | Yes, <10ms | **Shipped v18.26** |
|
|
141
|
-
| Page Understanding (DOM) | O(n) elements | No | Yes, <500ms | **Shipped v18.35** |
|
|
142
|
-
| Site Model Learning | O(1) amortized writes | No | Yes, <50ms | **Shipped v18.35** |
|
|
143
|
-
| Goal Decomposition | O(k×s) subgoals×strategies | No | Yes, <100ms | **Shipped v18.35** |
|
|
144
|
-
| siteFamiliarity gating | O(1) lookup | No | Yes, <1ms | **Shipped v18.35** |
|
|
145
|
-
|
|
146
|
-
**Key insight:** For d=26 traits, the Gaussian assumption gives closed-form solutions for everything. No GPU needed. The entire framework runs in pure TypeScript at sub-millisecond latency.
|
|
147
|
-
|
|
148
|
-
---
|
|
149
|
-
|
|
150
|
-
## Novel Contributions (What Nobody Has Done)
|
|
151
|
-
|
|
152
|
-
1. **First persona system with mathematically grounded cognitive distance** — W₁(personaA, personaB) — *shipped v18.27*
|
|
153
|
-
2. **First accessibility tool measuring transport-cost information loss** — *shipped v18.26*
|
|
154
|
-
3. **First adversarial UX testing via distributionally robust optimization** — Wasserstein balls around known personas — *shipped v18.27*
|
|
155
|
-
4. **First persona interpolation using displacement geodesics** — McCann interpolation preserves trait coupling — *shipped v18.27*
|
|
156
|
-
5. **First unified multi-layer OT accessibility score** — sum of transport costs across 6 cognitive layers — *shipped v18.27*
|
|
157
|
-
6. **First attention-as-transport model for web UX** — persona saliency via filtered W₂ — *shipped v18.28*
|
|
158
|
-
7. **First persistent site knowledge graph for browser automation** — navigation maps, element reliability, goal paths that accumulate across sessions — *shipped v18.35*
|
|
159
|
-
8. **First real-time page understanding via DOM analysis** — type classification, affordance mapping, form detection in <500ms — *shipped v18.35*
|
|
160
|
-
9. **First siteFamiliarity-gated cognitive simulation** — persona site knowledge auto-scales to actual data; no simulating expertise on unknown sites — *shipped v18.35*
|
|
161
|
-
10. **First research-backed cognitive disability personas** — autism spectrum (Yaneva 2018), intellectual disability (Karreman 2007), aphasia (W3C COGA), dyscalculia (UK Gov) — *shipped v18.35*
|
|
162
|
-
|
|
163
|
-
**Publishable gap identified:** No existing work computes W(expected_experience, actual_experience) for UX abandonment prediction. The neuroscience (Dabney), behavioral signals (Yamauchi), and frustration data (Ceaparu) exist separately but nobody has unified them under optimal transport.
|
|
164
|
-
|
|
165
|
-
---
|
|
166
|
-
|
|
167
|
-
## Implementation Status
|
|
168
|
-
|
|
169
|
-
| Phase | Feature | Status | Version |
|
|
170
|
-
|-------|---------|--------|---------|
|
|
171
|
-
| 1 | Trait space as probability measure + cognitive distance | **Shipped** | v18.27 |
|
|
172
|
-
| 2 | Adversarial persona generation via DRO | **Shipped** | v18.27 |
|
|
173
|
-
| 3 | Persona geodesic interpolation (McCann) | **Shipped** | v18.27 |
|
|
174
|
-
| 4 | Six-layer cognitive transport scoring | **Shipped** | v18.27 |
|
|
175
|
-
| 5 | Attention-as-transport saliency modeling | **Shipped** | v18.28 |
|
|
176
|
-
| 6 | Real-time page understanding (DOM analysis) | **Shipped** | v18.35 |
|
|
177
|
-
| 7 | Persistent site knowledge graph | **Shipped** | v18.35 |
|
|
178
|
-
| 8 | Cross-session browser profiles (AES-256-GCM) | **Shipped** | v18.35 |
|
|
179
|
-
| 9 | Autonomous goal decomposition | **Shipped** | v18.35 |
|
|
180
|
-
| 10 | siteFamiliarity trait + knowledge gating | **Shipped** | v18.35 |
|
|
181
|
-
| 11 | Research-backed disability personas (4 new) | **Shipped** | v18.35 |
|
|
182
|
-
|
|
183
|
-
All phases complete. 104 MCP tools, 26 cognitive traits, 21 personas (11 accessibility).
|
|
184
|
-
|
|
185
|
-
---
|
|
186
|
-
|
|
187
|
-
## Key References
|
|
188
|
-
|
|
189
|
-
### Neuroscience
|
|
190
|
-
- Taylor & Fiebach (2025) "Beyond Letters: OT for Sub-Letter Orthographic Processing" — Neurobiology of Language
|
|
191
|
-
- Galeotti, Citti, Sarti (2022) "Cortically Based Optimal Transport" — J. Math. Imaging & Vision
|
|
192
|
-
- Dehaene et al. (2021) "Compositional Neural Code for Written Words" — PNAS
|
|
193
|
-
- Xiao et al. (2025) "OT for Brain-Image Alignment" — ICCV
|
|
194
|
-
- Thual et al. (2022) "Fused Unbalanced Gromov-Wasserstein" — NeurIPS
|
|
195
|
-
- Aoun et al. (2023) "EMD for Spatial Memory Remapping" — Frontiers
|
|
196
|
-
- Dabney et al. (2020) "Distributional Code for Value" — Nature
|
|
197
|
-
- Janati et al. (2020) "Minimum Wasserstein Estimates for MEG/EEG" — NeuroImage
|
|
198
|
-
|
|
199
|
-
### HCI / UX
|
|
200
|
-
- Bylinskii et al. (2019) "Saliency Evaluation Metrics" — IEEE TPAMI
|
|
201
|
-
- Klein & Frintrop (2012) "W₂ Saliency Detection" — DAGM
|
|
202
|
-
- Rosenholtz et al. (2007) "Measuring Visual Clutter" — J. Vision
|
|
203
|
-
- Plonsky et al. (2022) "Wasserstein in Human Decision-Making" — Ann. Math. AI
|
|
204
|
-
- Grossman & Balakrishnan (2005) "Probabilistic 2D Pointing" — ACM TOCHI
|
|
205
|
-
- Rello & Baeza-Yates (2016) "Font Type and Dyslexia" — ACM TACCESS
|
|
206
|
-
- Perry, Zorzi, Ziegler (2019) "Personalized Dyslexia Models" — Psych. Science
|
|
207
|
-
- Yamauchi & Xiao (2018) "Cursor Emotion Reading" — Cognitive Science
|
|
208
|
-
|
|
209
|
-
### Disability / Accessibility HCI (v18.35)
|
|
210
|
-
- Yaneva et al. (2018) "Web Users with Autism: Eye Tracking Evidence" — Behaviour & IT
|
|
211
|
-
- Yaneva et al. (2020) "Keep It Simple: Eye-Tracking for ASD" — W4A
|
|
212
|
-
- Raymaker & Nicolaidis (2019) "AASPIRE Web Accessibility Guidelines" — PMC6485264
|
|
213
|
-
- Britto & Pizzolato (2016) "Interaction Design for ASD" — Semantic Scholar
|
|
214
|
-
- Karreman et al. (2007) "Accessible Website Content for ID" — J. Applied Research in ID
|
|
215
|
-
- Rocha et al. (2015) "Optimising Web Designs for Learning Disabilities" — PMC4467236
|
|
216
|
-
- W3C COGA (2024) "Cognitive Accessibility User Research" — W3C
|
|
217
|
-
- W3C COGA (2024) "Aphasia Research Module" — W3C
|
|
218
|
-
- W3C COGA (2024) "Dyscalculia Research Module" — W3C
|
|
219
|
-
- UK Gov Design System (2022) "Designing for Dyscalculia and Low Numeracy"
|
|
220
|
-
- Butterworth (2005) "Developmental Dyscalculia" — Science
|
|
221
|
-
- Cockburn et al. (2007) "Familiar Interfaces" — HCI
|
|
222
|
-
- Tauscher & Greenberg (1997) "How People Revisit Web Pages" — CHI
|
|
223
|
-
|
|
224
|
-
### Browser Agent Architecture (v18.35)
|
|
225
|
-
- AgentQ / MultiOn (2024) "MCTS-guided Browser Agent" — arXiv 2408.07199
|
|
226
|
-
- rtrvr.ai (2025) "DOM Intelligence Architecture" — 81.39% WebBench
|
|
227
|
-
- SeeAct (2024) "GPT-4V Grounding on Web Pages" — ICML
|
|
228
|
-
- Stagehand v3 (2025) "Action Caching with DOM Hash Validation" — Browserbase
|
|
229
|
-
- WebArena (2024) "Contextual Experience Replay" — 51% improvement with prior knowledge
|
|
230
|
-
|
|
231
|
-
### Mathematics
|
|
232
|
-
- Agueh & Carlier (2011) "Barycenters in Wasserstein Space" — SIAM
|
|
233
|
-
- Altschuler & Boix-Adsera (2022) "Barycenters are NP-Hard" — SIAM
|
|
234
|
-
- Esfahani & Kuhn (2018) "Data-driven DRO via Wasserstein" — Math. Programming
|
|
235
|
-
- Nadjahi et al. (2020) "Sliced Wasserstein Properties" — NeurIPS
|
|
236
|
-
- Izzo et al. (2021) "Dimensionality Reduction for Barycenters" — NeurIPS
|
|
237
|
-
- Zhu et al. (2023) "Geodesic Data Augmentation" — ICML
|
|
238
|
-
- Panaretos & Zemel (2020) "Statistics in Wasserstein Space" — Springer
|