cbrowser 17.6.0 → 18.0.0

package/docs/Tools-Accessibility.md

@@ -0,0 +1,202 @@
+# Accessibility Tools
+
+**Experience your site through the eyes of someone who can't use a mouse.**
+
+The `empathy_audit` tool simulates how people with disabilities actually experience your site — motor tremors that make clicking hard, low vision that requires zoom, ADHD that makes long forms impossible. This isn't a WCAG checklist. It's lived experience simulation.
+
+---
+
+## When to Use This Tool
+
+- **You think your site is accessible** but you've only run automated checkers
+- **You need to prioritize fixes** and want to know what actually impacts real users
+- **You're building for an aging population** and need to understand their struggles
+- **Compliance audits are coming** and you need to find issues before auditors do
+
+---
+
+## The Tool
+
+### `empathy_audit`
+
+**What it does**: Simulate disability personas navigating your site, detecting WCAG violations with the context of how they actually impact users.
+
+**Why you'd use it**: Automated accessibility checkers find violations. This tool shows you which violations actually matter and what the experience feels like.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `url` | string | Yes | URL to audit |
+| `personas` | array | No | Disability personas to simulate. Default: all |
+| `task` | string | No | Specific task to attempt (e.g., "complete checkout") |
+| `wcagLevel` | string | No | WCAG level: `A`, `AA`, `AAA`. Default: `AA` |
+
+**Example**:
+```json
+{
+  "url": "https://example.com/signup",
+  "personas": ["motor-tremor", "low-vision", "cognitive-adhd"],
+  "task": "Create an account"
+}
+```
+
+---
+
+## Disability Personas
+
+### `motor-tremor`
+
+**Simulates**: Essential tremor, Parkinson's disease, or any condition affecting fine motor control.
+
+**Behavioral Impact**:
+- Struggles with small click targets (< 44px)
+- Can't hover reliably for dropdown menus
+- Needs keyboard navigation
+- Frustrated by time-limited interactions
+
+**WCAG Focus**: Target size (2.5.5), Keyboard accessible (2.1.1), No timing (2.2.3)
+
+---
+
+### `low-vision`
+
+**Simulates**: Partial sight, macular degeneration, or conditions requiring magnification.
+
+**Behavioral Impact**:
+- Uses 200%+ zoom
+- Loses context when zoomed in
+- Needs high contrast
+- Can't see small text or icons without labels
+
+**WCAG Focus**: Reflow (1.4.10), Contrast (1.4.3), Text spacing (1.4.12)
+
+---
+
+### `cognitive-adhd`
+
+**Simulates**: ADHD, attention difficulties, executive function challenges.
+
+**Behavioral Impact**:
+- Skims rapidly, misses key information
+- Abandons long forms
+- Distracted by animations/movement
+- Needs clear visual hierarchy
+
+**WCAG Focus**: Pause/stop (2.2.2), Error prevention (3.3.4), Consistent navigation (3.2.3)
+
+---
+
+### `dyslexia`
+
+**Simulates**: Reading difficulties, letter/word recognition challenges.
+
+**Behavioral Impact**:
+- Struggles with dense text blocks
+- Needs clear typography and spacing
+- Misreads similar words
+- Benefits from icons alongside text
+
+**WCAG Focus**: Reading level (3.1.5), Line height (1.4.12), Clear fonts
+
+---
+
+### `deaf`
+
+**Simulates**: Deaf or hard of hearing users.
+
+**Behavioral Impact**:
+- Can't access audio content without captions
+- Misses audio alerts/notifications
+- Relies entirely on visual information
+- Needs sign language or text alternatives
+
+**WCAG Focus**: Captions (1.2.2), Audio description (1.2.5), Visual alternatives (1.4.1)
+
+---
+
+### `color-blind`
+
+**Simulates**: Color vision deficiency (protanopia, deuteranopia, tritanopia).
+
+**Behavioral Impact**:
+- Can't distinguish red/green, blue/yellow
+- Misses color-coded information
+- Needs patterns/labels in addition to color
+- Confused by red/green status indicators
+
+**WCAG Focus**: Use of color (1.4.1), Contrast (1.4.3)
+
+---
+
+## What the Audit Returns
+
+```json
+{
+  "persona": "motor-tremor",
+  "taskSuccess": false,
+  "abandonmentPoint": "Payment form - credit card expiry dropdown",
+  "timeToAbandon": 142,
+  "barriers": [
+    {
+      "type": "small-target",
+      "element": "#expiry-month",
+      "wcag": "2.5.5",
+      "severity": "critical",
+      "userImpact": "Cannot reliably click the 32px dropdown with tremor",
+      "remediation": "Increase target size to 44px minimum or provide keyboard alternative"
+    },
+    {
+      "type": "hover-dependent",
+      "element": ".nav-dropdown",
+      "wcag": "2.1.1",
+      "severity": "serious",
+      "userImpact": "Dropdown closes before user can move cursor into it",
+      "remediation": "Add click-to-open or increase hover delay"
+    }
+  ],
+  "wcagViolations": 7,
+  "recommendations": [
+    "Add keyboard navigation to all dropdowns",
+    "Increase minimum touch target to 44px",
+    "Add skip-to-content link"
+  ]
+}
+```
+
+---
+
+## Why This Is Different From WCAG Checkers
+
+| Traditional Checker | Empathy Audit |
+|--------------------|---------------|
+| "Image missing alt text" | "Blind user couldn't understand the product because the hero image has no description" |
+| "Target size 32px" | "User with tremor couldn't click the dropdown after 8 attempts" |
+| "Contrast ratio 3.8:1" | "Low vision user at 200% zoom couldn't read the error message" |
+| Reports violations | Reports **impact** |
+| Pass/fail metrics | Abandonment stories |
+
+---
+
+## Running Empathy Audits in CI/CD
+
+```bash
+# Quick audit before deploy
+npx cbrowser empathy-audit https://staging.example.com --personas motor-tremor,low-vision
+
+# Full audit with task
+npx cbrowser empathy-audit https://staging.example.com \
+  --task "Complete checkout" \
+  --wcag AA \
+  --output report.html
+```
+
+---
+
+## Related Documentation
+
+- [Persona Index](/docs/Persona-Index/) — All personas including accessibility
+- [UX Analysis Suite](/docs/UX-Analysis-Suite/) — Full UX analysis capabilities
+- [Constitutional Safety](/docs/Constitutional-Safety/) — How CBrowser handles sensitive operations
+
+---
+
+*Last updated: v17.6.0*

package/docs/Tools-Browser-Automation.md

@@ -0,0 +1,305 @@
+# Browser Automation Tools
+
+**Tell the browser what you want. Let AI figure out how.**
+
+These 12 tools handle navigation, clicking, form filling, data extraction, and page analysis. They replace brittle CSS selectors with natural language descriptions that survive DOM changes.
+
+---
+
+## When to Use These Tools
+
+- **You're automating a workflow** and tired of tests breaking when developers change class names
+- **You need to extract data** from pages without writing custom scrapers for each site
+- **You're building an AI agent** that needs to interact with arbitrary websites
+- **Your selectors keep failing** and you want something that self-heals
+
+---
+
+## Tools
+
+### `navigate`
+
+**What it does**: Opens a URL and takes a screenshot of the loaded page.
+
+**Why you'd use it**: Start any browser automation session or move between pages.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `url` | string | Yes | The URL to navigate to |
+
+**Example**:
+```json
+{
+  "url": "https://example.com/products"
+}
+```
+
+---
+
+### `click`
+
+**What it does**: Clicks an element using text content, CSS selector, or natural language description.
+
+**Why you'd use it**: Interact with buttons, links, or any clickable element without fragile selectors.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `selector` | string | Yes | What to click — text, CSS selector, or description like "the blue submit button" |
+| `force` | boolean | No | Bypass constitutional safety checks for destructive actions |
+| `verbose` | boolean | No | Return available elements and AI suggestions on failure |
+
+**Example**:
+```json
+{
+  "selector": "Add to Cart"
+}
+```
+
+Or with natural language:
+```json
+{
+  "selector": "the primary call-to-action button in the hero section"
+}
+```
+
+---
+
+### `smart_click`
+
+**What it does**: Clicks with automatic retry and self-healing selectors. If the original selector fails, it finds the element by intent.
+
+**Why you'd use it**: When elements might not be immediately available or when you want resilience against DOM changes.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `selector` | string | Yes | Element to click |
+| `maxRetries` | number | No | Maximum retry attempts. Default: 3 |
+| `dismissOverlays` | boolean | No | Automatically dismiss popups before clicking. Default: false |
+
+**Example**:
+```json
+{
+  "selector": "Submit Order",
+  "dismissOverlays": true
+}
+```
+
+**Note**: v11.8.0 added confidence gating — only reports success if the healed selector has ≥60% confidence.
+
+---
+
+### `fill`
+
+**What it does**: Types text into a form field identified by name, label, or description.
+
+**Why you'd use it**: Fill out forms without knowing the exact input names or IDs.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `selector` | string | Yes | The field to fill — label text, name attribute, or description |
+| `value` | string | Yes | Text to type into the field |
+| `clear` | boolean | No | Clear existing content before typing. Default: true |
+
+**Example**:
+```json
+{
+  "selector": "Email address",
+  "value": "user@example.com"
+}
+```
+
+---
+
+### `scroll`
+
+**What it does**: Scrolls the page in a specified direction or to a specific position.
+
+**Why you'd use it**: Reveal content below the fold, trigger lazy loading, or reach elements not yet visible.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `direction` | string | Yes | `up`, `down`, `top`, `bottom`, or pixel amount like `500px` |
+
+**Example**:
+```json
+{
+  "direction": "down"
+}
+```
+
+---
+
+### `screenshot`
+
+**What it does**: Captures the current page as an image.
+
+**Why you'd use it**: Document state, debug failures, or feed visual information to AI.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `fullPage` | boolean | No | Capture entire scrollable page. Default: false (viewport only) |
+| `path` | string | No | Save to file path instead of returning base64 |
+
+**Example**:
+```json
+{
+  "fullPage": true
+}
+```
+
+---
+
+### `extract`
+
+**What it does**: Pulls structured data from the page — links, headings, forms, images, or arbitrary text.
+
+**Why you'd use it**: Scrape content, analyze page structure, or gather data for further processing.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `type` | string | Yes | What to extract: `links`, `headings`, `forms`, `images`, `text`, or `all` |
+| `selector` | string | No | Limit extraction to elements matching this selector |
+
+**Example**:
+```json
+{
+  "type": "links"
+}
+```
+
+Returns structured JSON with all links, their text, and href values.
+
+---
+
+### `find_element_by_intent`
+
+**What it does**: Uses AI to find elements by semantic description. Returns the best match with confidence score and accessibility information.
+
+**Why you'd use it**: When you need to find something but don't know exactly how it's implemented — "the navigation menu" or "the search box in the header".
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `intent` | string | Yes | Natural language description of the element |
+| `context` | string | No | Additional context to narrow the search |
+
+**Example**:
+```json
+{
+  "intent": "the main call-to-action button",
+  "context": "in the pricing section"
+}
+```
+
+**Returns**: Selector, confidence score (0-1), accessibility score, and alternative matches.
+
+**Note**: v7.4.17 added ARIA-first strategy — prioritizes `aria-label`, `role`, semantic HTML before falling back to classes/IDs.
+
+---
+
+### `analyze_page`
+
+**What it does**: Examines page structure and returns inventory of interactive elements — forms, buttons, links, inputs.
+
+**Why you'd use it**: Understand what's on a page before deciding what to interact with. Essential for building adaptive agents.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `detailed` | boolean | No | Include element attributes and positions. Default: false |
+
+**Example**:
+```json
+{
+  "detailed": true
+}
+```
+
+---
+
+### `assert`
+
+**What it does**: Verifies a condition using natural language and returns pass/fail with explanation.
+
+**Why you'd use it**: Validate that actions had the expected result without writing complex assertion logic.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `condition` | string | Yes | What to check, in plain English |
+
+**Example**:
+```json
+{
+  "condition": "the shopping cart shows 2 items"
+}
+```
+
+**Returns**: `{ "passed": true/false, "reason": "explanation" }`
+
+---
+
+### `dismiss_overlay`
+
+**What it does**: Detects and closes modal overlays — cookie consent banners, newsletter popups, age verification gates.
+
+**Why you'd use it**: Clear blocking UI before interacting with the actual page content.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `type` | string | No | Overlay type: `auto`, `cookie`, `age-verify`, `newsletter`, `custom`. Default: `auto` |
+| `customSelector` | string | No | Selector for custom overlay close button |
+
+**Example**:
+```json
+{
+  "type": "auto"
+}
+```
+
+**Note**: Constitutional Yellow zone — logged but proceeds automatically.
+
+---
+
+### `ask_user`
+
+**What it does**: Creates a structured prompt to ask the human operator a question with predefined options.
+
+**Why you'd use it**: When the automation needs human input to proceed — confirmation, selection, or decision that can't be automated.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `question` | string | Yes | The question to ask |
+| `options` | array | No | Predefined answer options |
+| `allowFreeform` | boolean | No | Allow typed response. Default: true |
+
+**Example**:
+```json
+{
+  "question": "Which shipping method should I select?",
+  "options": ["Standard (5-7 days)", "Express (2-3 days)", "Overnight"]
+}
+```
+
+---
+
+## How Self-Healing Works
+
+When a selector fails, CBrowser:
+
+1. **Checks the healing cache** for previously learned mappings
+2. **Analyzes the page** for elements matching the semantic intent
+3. **Scores candidates** by text similarity, position, and accessibility attributes
+4. **Returns the best match** if confidence exceeds 60%
+5. **Caches the mapping** for faster future lookups
+
+This means your automation adapts to site changes automatically. A redesign that moves the "Add to Cart" button? CBrowser finds it by intent, not by its old CSS class.
+
+---
+
+## Related Documentation
+
+- [Constitutional Safety](/docs/Constitutional-Safety/) — How CBrowser classifies action risk
+- [Tools Overview](/docs/Tools-Overview/) — All tools by category
+- [Examples](/docs/Examples/) — Real-world automation patterns
+
+---
+
+*Last updated: v17.6.0*