cbrowser 17.6.0 → 18.0.0

package/docs/Tool-Empathy-Audit.md

@@ -0,0 +1,325 @@
+# Empathy Audit
+
+**Experience your site through the eyes of someone with a disability.**
+
+`empathy_audit` doesn't just check WCAG compliance — it simulates actual humans with motor tremors, vision impairment, ADHD, and other conditions navigating your site. You'll see where they struggle, what makes them give up, and get specific remediation guidance.
+
+---
+
+## Quick Start
+
+```json
+{
+  "url": "https://example.com/checkout",
+  "personas": ["motor-tremor", "low-vision", "cognitive-adhd"],
+  "task": "Complete a purchase"
+}
+```
+
+**What happens**:
+1. Each disability persona attempts the task
+2. Their specific impairments affect how they interact (tremor = missed clicks, low vision = can't read small text)
+3. WCAG violations are detected and mapped to real user impact
+4. You get actionable remediation for each issue
+
+---
+
+## Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `url` | string | Yes | — | Page to audit |
+| `personas` | array | No | All | Disability personas to simulate |
+| `task` | string | No | General exploration | Specific task to attempt |
+| `wcagLevel` | string | No | `AA` | WCAG conformance level: `A`, `AA`, `AAA` |
+| `depth` | number | No | 1 | Pages to crawl |
+
+---
+
+## Disability Personas
+
+### `motor-tremor`
+
+**Simulates**: Essential tremor, Parkinson's, cerebral palsy, repetitive strain injury.
+
+**Behavioral Characteristics**:
+- Mouse movement is imprecise with jitter
+- Clicking small targets fails repeatedly
+- Can't maintain hover long enough for menus
+- Double-clicks unintentionally
+- Strongly prefers keyboard navigation
+
+**Common Barriers Detected**:
+
+| Barrier | WCAG | User Experience |
+|---------|------|-----------------|
+| Small click targets | 2.5.5 | 8 attempts to click a 24px button |
+| Hover-dependent menus | 2.1.1 | Menu closes before cursor reaches it |
+| Time-limited forms | 2.2.3 | Session expired during slow typing |
+| No keyboard shortcuts | 2.1.1 | Forced to use mouse for everything |
+
+---
+
+### `low-vision`
+
+**Simulates**: Macular degeneration, glaucoma, cataracts, legal blindness with partial sight.
+
+**Behavioral Characteristics**:
+- Uses 200-400% browser zoom
+- Relies on high contrast
+- Loses page context when zoomed
+- Can't perceive small text or icons
+- Needs clear visual hierarchy
+
+**Common Barriers Detected**:
+
+| Barrier | WCAG | User Experience |
+|---------|------|-----------------|
+| Fixed-width containers | 1.4.10 | Content cut off at 200% zoom |
+| Low contrast text | 1.4.3 | Can't read gray-on-white body text |
+| Icon-only buttons | 1.1.1 | No idea what the hamburger menu does |
+| Tiny form labels | 1.4.4 | Can't tell which field is which |
+
+---
+
+### `cognitive-adhd`
+
+**Simulates**: ADHD, executive function challenges, attention difficulties.
+
+**Behavioral Characteristics**:
+- Scans rapidly, doesn't read thoroughly
+- Clicks impulsively, sometimes wrong targets
+- Abandons long forms or processes
+- Easily distracted by movement/animation
+- Loses track of progress in multi-step flows
+
+**Common Barriers Detected**:
+
+| Barrier | WCAG | User Experience |
+|---------|------|-----------------|
+| Wall of text | 3.1.5 | Glazed over and missed key info |
+| Auto-playing video | 2.2.2 | Couldn't focus on the form |
+| No progress indicator | 3.3.4 | Didn't know how many steps remained |
+| Long forms | 3.3.2 | Abandoned at field 12 of 20 |
+
+---
+
+### `dyslexia`
+
+**Simulates**: Reading difficulties, letter reversal, word recognition challenges.
+
+**Behavioral Characteristics**:
+- Slow reading speed
+- Misreads similar words (their/there, form/from)
+- Struggles with justified text
+- Benefits from icons alongside text
+- Needs generous line spacing
+
+**Common Barriers Detected**:
+
+| Barrier | WCAG | User Experience |
+|---------|------|-----------------|
+| Justified text | Best practice | Letters swim, lost place |
+| Dense paragraphs | 1.4.12 | Couldn't parse the content |
+| Ambiguous labels | 3.3.2 | Confused "Email" for "E-mail" link |
+| Poor font choice | Best practice | Letters hard to distinguish |
+
+---
+
+### `deaf`
+
+**Simulates**: Deaf, hard of hearing, auditory processing disorder.
+
+**Behavioral Characteristics**:
+- Can't hear audio content
+- Misses audio alerts/notifications
+- Depends entirely on visual information
+- Needs captions or transcripts
+- May need sign language
+
+**Common Barriers Detected**:
+
+| Barrier | WCAG | User Experience |
+|---------|------|-----------------|
+| Video without captions | 1.2.2 | Missed entire product demo |
+| Audio-only alerts | 1.4.2 | Didn't know an error occurred |
+| Phone-only support | Best practice | No way to get help |
+
+---
+
+### `color-blind`
+
+**Simulates**: Protanopia, deuteranopia, tritanopia, and other color vision deficiencies.
+
+**Behavioral Characteristics**:
+- Can't distinguish red/green (most common)
+- May confuse blue/yellow (less common)
+- Depends on patterns, labels, position
+- Struggles with color-coded status
+
+**Common Barriers Detected**:
+
+| Barrier | WCAG | User Experience |
+|---------|------|-----------------|
+| Red/green validation | 1.4.1 | Can't tell which fields have errors |
+| Color-only charts | 1.4.1 | Graphs are meaningless |
+| Status indicators | 1.4.1 | All traffic lights look the same |
+
+---
+
+## Output
+
+```json
+{
+  "url": "https://example.com/checkout",
+  "wcagLevel": "AA",
+  "personas": {
+    "motor-tremor": {
+      "taskSuccess": false,
+      "abandonmentPoint": "Payment form - credit card expiry dropdown",
+      "timeToAbandon": 142,
+      "attempts": {
+        "clicks": 47,
+        "missedClicks": 23,
+        "successfulClicks": 24
+      },
+      "barriers": [
+        {
+          "type": "small-target",
+          "element": "#expiry-month",
+          "wcag": "2.5.5",
+          "severity": "critical",
+          "targetSize": "32x24",
+          "requiredSize": "44x44",
+          "userImpact": "Required 8 attempts to click, user patience exhausted",
+          "remediation": {
+            "summary": "Increase dropdown trigger to 44x44px minimum",
+            "code": "<select style='min-width: 44px; min-height: 44px;'>",
+            "effort": "low"
+          }
+        }
+      ]
+    },
+    "low-vision": {
+      "taskSuccess": true,
+      "timeToComplete": 287,
+      "zoomLevel": "200%",
+      "barriers": [
+        {
+          "type": "low-contrast",
+          "element": ".help-text",
+          "wcag": "1.4.3",
+          "severity": "moderate",
+          "contrastRatio": "3.2:1",
+          "requiredRatio": "4.5:1",
+          "userImpact": "Couldn't read CVV help text, had to guess format",
+          "remediation": {
+            "summary": "Increase text contrast to 4.5:1",
+            "code": "color: #595959; /* was #999999 */",
+            "effort": "low"
+          }
+        }
+      ]
+    }
+  },
+  "summary": {
+    "totalBarriers": 7,
+    "critical": 2,
+    "serious": 3,
+    "moderate": 2,
+    "wcagViolations": {
+      "A": 1,
+      "AA": 4
+    },
+    "recommendations": [
+      "Increase all interactive targets to 44px minimum",
+      "Add keyboard navigation to dropdown menus",
+      "Improve contrast ratio on help text",
+      "Add visible focus indicators"
+    ]
+  }
+}
+```
+
+---
+
+## Use Cases
+
+### 1. Pre-Launch Accessibility Review
+
+Before launching a new feature, run empathy audits across all disability personas:
+
+```json
+{
+  "url": "https://staging.example.com/new-feature",
+  "personas": ["motor-tremor", "low-vision", "cognitive-adhd", "deaf", "color-blind"],
+  "task": "Complete the new onboarding flow"
+}
+```
+
+---
+
+### 2. Prioritizing Accessibility Fixes
+
+You have 100 WCAG violations. Which ones matter?
+
+```json
+{
+  "url": "https://example.com",
+  "depth": 5
+}
+```
+
+The audit shows which violations caused actual abandonment vs minor inconvenience. Fix the critical ones first.
+
+---
+
+### 3. Compliance Documentation
+
+Need evidence for VPAT or accessibility statement:
+
+```json
+{
+  "url": "https://example.com",
+  "wcagLevel": "AA",
+  "depth": 10
+}
+```
+
+Generates detailed barrier documentation with WCAG mappings.
+
+---
+
+## Why This Is Different
+
+| WCAG Checker | Empathy Audit |
+|--------------|---------------|
+| "Button has no accessible name" | "Blind user couldn't proceed because the 'Next' button had no label" |
+| "Contrast ratio is 3.2:1" | "Low-vision user at 200% zoom couldn't read the error message and submitted invalid data" |
+| "Target size is 32px" | "User with tremor failed to click the dropdown 8 times before giving up" |
+| Counts violations | Predicts abandonment |
+| Compliance-focused | User-experience-focused |
+
+---
+
+## CI/CD Integration
+
+```bash
+# Fail build if critical accessibility barriers found
+npx cbrowser empathy-audit https://staging.example.com \
+  --task "Complete checkout" \
+  --fail-on critical \
+  --output accessibility-report.html
+```
+
+---
+
+## Related Tools
+
+- [`cognitive_journey_autonomous`](/docs/Tool-Cognitive-Journey-Autonomous/) — Full journey simulation
+- [`agent_ready_audit`](/docs/Tools-Utilities/) — AI agent friendliness
+- [UX Analysis Suite](/docs/UX-Analysis-Suite/) — Full UX analysis capabilities
+
+---
+
+*Last updated: v17.6.0*

package/docs/Tool-Hunt-Bugs.md

@@ -0,0 +1,299 @@
+# Hunt Bugs
+
+**Turn AI loose on your site. See what's broken.**
+
+`hunt_bugs` is autonomous exploratory testing. You give it a URL, it crawls your site looking for bugs — broken links, JavaScript errors, accessibility issues, visual glitches, and security problems. No test cases required.
+
+---
+
+## Quick Start
+
+```json
+{
+  "url": "https://example.com",
+  "scope": "all",
+  "depth": 4,
+  "maxPages": 50
+}
+```
+
+**What happens**:
+1. AI starts at your URL and begins exploring
+2. On each page, it checks for functional, visual, accessibility, and security issues
+3. It follows links, fills forms, clicks buttons — looking for things that break
+4. You get a report of everything found, with reproduction steps and screenshots
+
+---
+
+## Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `url` | string | Yes | — | Starting URL |
+| `scope` | string | No | `all` | Bug types: `all`, `functional`, `visual`, `accessibility`, `security` |
+| `depth` | number | No | 3 | How deep to crawl |
+| `maxPages` | number | No | 20 | Maximum pages to visit |
+| `focus` | string | No | — | Focus area (e.g., "forms", "checkout", "navigation") |
+| `exclude` | array | No | — | URL patterns to skip |
+
+---
+
+## What It Finds
+
+### Functional Bugs
+
+| Bug Type | How It's Detected |
+|----------|-------------------|
+| Broken links | Links that return 4xx/5xx errors |
+| Dead ends | Pages with no way to navigate away |
+| Form errors | Submissions that fail silently |
+| JavaScript exceptions | Console errors during interaction |
+| Failed network requests | XHR/fetch that error |
+| Infinite loops | Redirect chains, infinite scrolls |
+| Missing content | Empty states, placeholder text |
+
+### Visual Bugs
+
+| Bug Type | How It's Detected |
+|----------|-------------------|
+| Overlapping elements | Content that covers other content |
+| Horizontal overflow | Content breaking viewport |
+| Missing images | Broken `src` attributes |
+| Layout breaks | Elements far from expected position |
+| Z-index issues | Content hidden behind other layers |
+| Responsive failures | Elements that break at viewport edges |
+
+### Accessibility Bugs
+
+| Bug Type | How It's Detected |
+|----------|-------------------|
+| Missing alt text | Images without descriptions |
+| Low contrast | Text that fails WCAG contrast |
+| Keyboard traps | Can't escape a component with keyboard |
+| Missing labels | Form fields without associated labels |
+| Focus issues | Interactive elements without focus styles |
+| ARIA violations | Invalid ARIA attributes |
+
+### Security Issues
+
+| Bug Type | How It's Detected |
+|----------|-------------------|
+| Exposed credentials | Visible API keys, passwords |
+| Insecure forms | HTTP forms on HTTPS pages |
+| Data in URLs | Sensitive info in query strings |
+| Missing HTTPS | Insecure resource loading |
+| Open redirects | Redirects to external domains |
+| Debug endpoints | Exposed dev/debug routes |
+
+---
+
+## Output
+
+```json
+{
+  "url": "https://example.com",
+  "pagesVisited": 34,
+  "timeElapsed": 187,
+  "bugs": [
+    {
+      "severity": "critical",
+      "type": "functional",
+      "category": "form-error",
+      "url": "https://example.com/checkout",
+      "description": "Payment form silently fails when CVV is left empty",
+      "reproduction": [
+        "Navigate to /checkout",
+        "Fill all fields except CVV",
+        "Click 'Pay Now'",
+        "Form shows loading spinner but never completes"
+      ],
+      "screenshot": "base64...",
+      "consoleErrors": [
+        "Uncaught TypeError: Cannot read property 'value' of null at payment.js:142"
+      ]
+    },
+    {
+      "severity": "serious",
+      "type": "accessibility",
+      "category": "missing-label",
+      "url": "https://example.com/contact",
+      "description": "Phone number field has no associated label",
+      "wcag": "1.3.1",
+      "element": "<input type='tel' name='phone' placeholder='Phone'>",
+      "remediation": "Add <label for='phone'>Phone Number</label>"
+    },
+    {
+      "severity": "moderate",
+      "type": "visual",
+      "category": "overflow",
+      "url": "https://example.com/pricing",
+      "description": "Pricing table overflows viewport on mobile",
+      "viewport": "375x667",
+      "screenshot": "base64..."
+    },
+    {
+      "severity": "serious",
+      "type": "security",
+      "category": "exposed-credentials",
+      "url": "https://example.com/config",
+      "description": "API key visible in page source",
+      "evidence": "const API_KEY = 'sk-...'",
+      "recommendation": "Move API key to environment variable"
+    }
+  ],
+  "summary": {
+    "critical": 1,
+    "serious": 4,
+    "moderate": 7,
+    "minor": 12,
+    "byType": {
+      "functional": 6,
+      "visual": 8,
+      "accessibility": 5,
+      "security": 5
+    }
+  }
+}
+```
+
+---
+
+## Use Cases
+
+### 1. Pre-Release Smoke Test
+
+Before deploying, run a quick bug hunt:
+
+```json
+{
+  "url": "https://staging.example.com",
+  "scope": "functional",
+  "depth": 3,
+  "maxPages": 30
+}
+```
+
+Catches obvious breaks before they reach production.
+
+---
+
+### 2. Security Reconnaissance
+
+Find exposed secrets and vulnerabilities:
+
+```json
+{
+  "url": "https://example.com",
+  "scope": "security",
+  "depth": 5,
+  "maxPages": 100
+}
+```
+
+---
+
+### 3. Accessibility Sweep
+
+Find accessibility issues across the entire site:
+
+```json
+{
+  "url": "https://example.com",
+  "scope": "accessibility",
+  "depth": 5
+}
+```
+
+For deeper analysis of specific issues, follow up with [empathy_audit](/docs/Tool-Empathy-Audit/).
+
+---
+
+### 4. Focused Testing
+
+Hunt bugs only in a specific area:
+
+```json
+{
+  "url": "https://example.com/checkout",
+  "focus": "checkout",
+  "exclude": ["/blog/*", "/docs/*"]
+}
+```
+
+---
+
+## How It Explores
+
+1. **Starts at your URL** and analyzes the page
+2. **Identifies interactive elements** — links, buttons, forms
+3. **Executes interactions** — clicks, fills, submits
+4. **Records everything** — console logs, network, screenshots
+5. **Follows promising paths** — prioritizes unexplored areas
+6. **Avoids traps** — detects infinite loops, skips logout/delete
+7. **Moves to next page** and repeats
+
+The AI uses constitutional safety rules to avoid destructive actions — it won't click "Delete Account" or "Cancel Subscription".
+
+---
+
+## CI/CD Integration
+
+```bash
+# Run in CI, fail if critical bugs found
+npx cbrowser hunt-bugs https://staging.example.com \
+  --scope all \
+  --depth 3 \
+  --fail-on critical \
+  --output bugs.json
+
+# Generate HTML report
+npx cbrowser hunt-bugs https://example.com \
+  --output report.html
+```
+
+---
+
+## Tips
+
+### Start Shallow, Go Deep
+
+```json
+// First run: quick sweep
+{ "depth": 2, "maxPages": 20 }
+
+// Second run: deep dive on problem areas
+{ "url": "https://example.com/checkout", "depth": 5 }
+```
+
+### Exclude Known Issues
+
+```json
+{
+  "exclude": [
+    "/legacy/*",  // Old pages being deprecated
+    "/admin/*"    // Requires auth
+  ]
+}
+```
+
+### Focus on What Matters
+
+```json
+// Only care about checkout working?
+{ "focus": "checkout", "scope": "functional" }
+
+// Preparing for accessibility audit?
+{ "scope": "accessibility", "depth": 10 }
+```
+
+---
+
+## Related Tools
+
+- [`nl_test_file`](/docs/Tools-Testing-Quality/) — Run specific test scenarios
+- [`empathy_audit`](/docs/Tool-Empathy-Audit/) — Deep accessibility testing
+- [`competitive_benchmark`](/docs/Tool-Competitive-Benchmark/) — Compare against competitors
+
+---
+
+*Last updated: v17.6.0*