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.
Files changed (71) hide show
  1. package/package.json +1 -1
  2. package/docs/ASSESSMENT.md +0 -132
  3. package/docs/AUTH0-SETUP.md +0 -207
  4. package/docs/COGNITIVE-OPTIMAL-TRANSPORT-RESEARCH.md +0 -238
  5. package/docs/DEMO-DEPLOYMENT.md +0 -177
  6. package/docs/ENTERPRISE-INTEGRATION.md +0 -250
  7. package/docs/GETTING-STARTED.md +0 -232
  8. package/docs/INSTALL.md +0 -274
  9. package/docs/MCP-INTEGRATION.md +0 -301
  10. package/docs/METHODOLOGY.md +0 -276
  11. package/docs/PERSONA-QUESTIONNAIRE.md +0 -328
  12. package/docs/README.md +0 -45
  13. package/docs/REMOTE-MCP-SERVER.md +0 -569
  14. package/docs/SECURITY_WHITEPAPER.md +0 -475
  15. package/docs/STRESS-TEST-v16.14.4.md +0 -241
  16. package/docs/Tool-Cognitive-Journey-Autonomous.md +0 -270
  17. package/docs/Tool-Competitive-Benchmark.md +0 -293
  18. package/docs/Tool-Empathy-Audit.md +0 -331
  19. package/docs/Tool-Hunt-Bugs.md +0 -305
  20. package/docs/Tool-Marketing-Campaign.md +0 -298
  21. package/docs/Tool-Persona-Create.md +0 -274
  22. package/docs/Tools-Accessibility.md +0 -208
  23. package/docs/Tools-Browser-Automation.md +0 -311
  24. package/docs/Tools-Cognitive-Journeys.md +0 -233
  25. package/docs/Tools-Marketing-Intelligence.md +0 -271
  26. package/docs/Tools-Overview.md +0 -162
  27. package/docs/Tools-Persona-System.md +0 -300
  28. package/docs/Tools-Session-State.md +0 -278
  29. package/docs/Tools-Testing-Quality.md +0 -257
  30. package/docs/Tools-Utilities.md +0 -182
  31. package/docs/Tools-Visual-Performance.md +0 -278
  32. package/docs/hunt-bugs-coverage.md +0 -103
  33. package/docs/personas/Persona-ADHD.md +0 -141
  34. package/docs/personas/Persona-ElderlyUser.md +0 -137
  35. package/docs/personas/Persona-FirstTimer.md +0 -137
  36. package/docs/personas/Persona-ImpatientUser.md +0 -138
  37. package/docs/personas/Persona-Index.md +0 -302
  38. package/docs/personas/Persona-LowVision.md +0 -139
  39. package/docs/personas/Persona-MobileUser.md +0 -139
  40. package/docs/personas/Persona-MotorTremor.md +0 -139
  41. package/docs/personas/Persona-PowerUser.md +0 -135
  42. package/docs/personas/Persona-ScreenReaderUser.md +0 -139
  43. package/docs/research/Bibliography.md +0 -275
  44. package/docs/research/Research-Methodology.md +0 -244
  45. package/docs/research/Values-Research.md +0 -432
  46. package/docs/traits/Trait-AnchoringBias.md +0 -227
  47. package/docs/traits/Trait-AttributionStyle.md +0 -280
  48. package/docs/traits/Trait-AuthoritySensitivity.md +0 -141
  49. package/docs/traits/Trait-ChangeBlindness.md +0 -171
  50. package/docs/traits/Trait-Comprehension.md +0 -180
  51. package/docs/traits/Trait-Curiosity.md +0 -189
  52. package/docs/traits/Trait-EmotionalContagion.md +0 -144
  53. package/docs/traits/Trait-FOMO.md +0 -150
  54. package/docs/traits/Trait-Index.md +0 -166
  55. package/docs/traits/Trait-InformationForaging.md +0 -217
  56. package/docs/traits/Trait-InterruptRecovery.md +0 -249
  57. package/docs/traits/Trait-MentalModelRigidity.md +0 -228
  58. package/docs/traits/Trait-MetacognitivePlanning.md +0 -164
  59. package/docs/traits/Trait-Patience.md +0 -137
  60. package/docs/traits/Trait-Persistence.md +0 -165
  61. package/docs/traits/Trait-ProceduralFluency.md +0 -205
  62. package/docs/traits/Trait-ReadingTendency.md +0 -216
  63. package/docs/traits/Trait-Resilience.md +0 -162
  64. package/docs/traits/Trait-RiskTolerance.md +0 -162
  65. package/docs/traits/Trait-Satisficing.md +0 -181
  66. package/docs/traits/Trait-SelfEfficacy.md +0 -199
  67. package/docs/traits/Trait-SocialProofSensitivity.md +0 -155
  68. package/docs/traits/Trait-TimeHorizon.md +0 -267
  69. package/docs/traits/Trait-TransferLearning.md +0 -249
  70. package/docs/traits/Trait-TrustCalibration.md +0 -227
  71. 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.0",
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",
@@ -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.*
@@ -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