librefang-registry/hands/browser/SKILL.md

---
name: browser-automation
version: "1.0.0"
description: Playwright-based browser automation patterns for autonomous web interaction
author: LibreFang
tags: [browser, automation, playwright, web, scraping]
tools: [browser_navigate, browser_click, browser_type, browser_screenshot, browser_read_page, browser_close]
runtime: prompt_only
---

# Browser Automation Skill

## Playwright CSS Selector Reference

### Basic Selectors
| Selector | Description | Example |
|----------|-------------|---------|
| `#id` | By ID | `#checkout-btn` |
| `.class` | By class | `.add-to-cart` |
| `tag` | By element | `button`, `input` |
| `[attr=val]` | By attribute | `[data-testid="submit"]` |
| `tag.class` | Combined | `button.primary` |
| `parent child` | Descendant | `div.container button` |
| `parent > child` | Direct child | `ul > li` |
| `:nth-child(n)` | Nth element | `li:nth-child(2)` |
| `:first-child` | First element | `ul > li:first-child` |
| `:last-child` | Last element | `ul > li:last-child` |
| `[attr*=val]` | Attribute contains | `[class*="price"]` |
| `[attr^=val]` | Attribute starts with | `[href^="https"]` |
| `[attr$=val]` | Attribute ends with | `[href$=".pdf"]` |
| `:not(sel)` | Negation | `button:not(.disabled)` |
| `sel1, sel2` | Multiple selectors | `#submit, button[type="submit"]` |

### Form Selectors
| Selector | Use Case |
|----------|----------|
| `input[type="email"]` | Email fields |
| `input[type="password"]` | Password fields |
| `input[type="search"]` | Search boxes |
| `input[name="q"]` | Google/search query |
| `textarea` | Multi-line text areas |
| `select[name="country"]` | Dropdown menus |
| `input[type="checkbox"]` | Checkboxes |
| `input[type="radio"]` | Radio buttons |
| `button[type="submit"]` | Submit buttons |
| `input[type="file"]` | File upload fields |
| `input[type="date"]` | Date pickers |
| `input[type="tel"]` | Phone number fields |
| `input[autocomplete="cc-number"]` | Credit card fields |
| `[contenteditable="true"]` | Rich text editors |

### Navigation Selectors
| Selector | Use Case |
|----------|----------|
| `a[href*="cart"]` | Cart links |
| `a[href*="checkout"]` | Checkout links |
| `a[href*="login"]` | Login links |
| `nav a` | Navigation menu links |
| `.breadcrumb a` | Breadcrumb links |
| `[role="navigation"] a` | ARIA nav links |
| `a[href*="account"]` | Account/profile links |
| `a[href*="register"], a[href*="signup"]` | Registration links |
| `header a[href="/"]` | Logo/home link |
| `footer a` | Footer links |

### E-commerce Selectors
| Selector | Use Case |
|----------|----------|
| `.product-price`, `[data-price]` | Product prices |
| `.add-to-cart`, `#add-to-cart` | Add to cart buttons |
| `.cart-total`, `.order-total` | Cart total |
| `.quantity`, `input[name="quantity"]` | Quantity selectors |
| `.checkout-btn`, `#checkout` | Checkout buttons |
| `[data-product-id]` | Product identifiers |
| `.product-title`, `h1.product-name` | Product names |
| `.product-image img`, `[data-zoom-image]` | Product images |
| `.star-rating`, `[data-rating]` | Review ratings |
| `.in-stock`, `.availability` | Stock status |
| `select[name="size"], .size-selector` | Size selectors |
| `[data-variant], .color-swatch` | Variant selectors |

---

## Generic Selector Strategies (Priority Order)

Use selectors that are resilient to UI redesigns. Prefer semantic and accessibility-based selectors over class names.

### Tier 1 — Test Attributes (most stable)
| Selector | Description |
|----------|-------------|
| `[data-testid="value"]` | Explicit test ID — survives refactors |
| `[data-test="value"]` | Alternative test attribute convention |
| `[data-cy="value"]` | Cypress test attribute |
| `[data-qa="value"]` | QA-specific test attribute |

### Tier 2 — Accessibility Attributes
| Selector | Description |
|----------|-------------|
| `[aria-label="Search"]` | Accessible name, framework-agnostic |
| `[aria-labelledby="id"]` | References a labelling element |
| `[role="button"]` | ARIA role — semantic intent |
| `[role="link"]` | ARIA link role |
| `[role="textbox"]` | ARIA textbox role |
| `[role="dialog"]` | Modals and popups |
| `[role="navigation"]` | Navigation landmarks |
| `[role="search"]` | Search landmarks |
| `[aria-expanded="true"]` | Open dropdowns/menus |
| `[aria-selected="true"]` | Selected tabs/options |
| `[aria-checked="true"]` | Checked checkboxes/radios |
| `[aria-disabled="true"]` | Disabled elements (do not click) |

### Tier 3 — Semantic HTML
| Selector | Description |
|----------|-------------|
| `button[type="submit"]` | Form submit buttons |
| `input[name="fieldname"]` | Form fields by name |
| `input[type="email"]` | Email input by type |
| `label[for="fieldid"]` | Label linked to input |
| `nav a` | Navigation links |
| `main`, `article`, `section` | Content landmarks |
| `header`, `footer` | Page structure |
| `h1`, `h2`, `h3` | Headings for orientation |

### Tier 4 — ID and Visible Text
| Strategy | When to use |
|----------|-------------|
| `#unique-id` | When ID is human-readable and stable |
| Visible text content | When no good attribute selectors exist |
| `a:has-text("Sign In")` | Playwright-specific text matching |

### Tier 5 — Class Selectors (least stable)
| Risk | Pattern |
|------|---------|
| Low risk | `.btn-primary`, `.nav-link` (design-system classes) |
| Medium risk | `.header-search-input` (component-specific) |
| High risk | `.css-1a2b3c`, `.sc-fAbCdE` (auto-generated by CSS-in-JS) |

**Rule:** Never rely on auto-generated class names (random strings like `.css-xyz123`). These change on every build.

## Accessibility-Based Interaction Patterns

Modern web apps expose accessibility attributes that are more stable than CSS classes.

### Finding Interactive Elements by Role
```
Buttons:     [role="button"], button
Links:       [role="link"], a[href]
Text inputs: [role="textbox"], input[type="text"], textarea
Checkboxes:  [role="checkbox"], input[type="checkbox"]
Radio:       [role="radio"], input[type="radio"]
Comboboxes:  [role="combobox"] (autocomplete/typeahead fields)
Tabs:        [role="tab"] (tab navigation)
Menus:       [role="menu"], [role="menuitem"]
Dialogs:     [role="dialog"], [role="alertdialog"]
```

### Reading Page Structure via Landmarks
```
[role="banner"]       → site header (logo, global nav)
[role="navigation"]   → navigation sections
[role="main"]         → primary page content
[role="search"]       → search functionality
[role="contentinfo"]  → footer (copyright, legal links)
[role="complementary"] → sidebar content
[role="form"]         → form regions
```

### Label-Based Field Identification
```
Instead of guessing input selectors, find labels first:
1. browser_read_page → look for label text (e.g., "Email Address")
2. Use: label:has-text("Email") + input  (sibling)
   Or:  input[aria-label="Email Address"]
   Or:  #<id-from-label-for-attribute>
```

## SPA Framework Detection & Handling

### Detecting the Framework
| Signal | Framework | Notes |
|--------|-----------|-------|
| `<div id="root">` or `<div id="__next">` | React / Next.js | Content rendered client-side |
| `<div id="app">` with `data-v-` attributes | Vue.js / Nuxt | `data-v-xxxxx` are scoped style markers |
| `<app-root>` or custom element tags | Angular | Uses web component-like tags |
| `<div id="svelte">` or compiled class names | Svelte / SvelteKit | Minimal runtime footprint |
| URL contains `#/` hash routing | Any SPA | Client-side routing via hash |
| `__NEXT_DATA__` script tag | Next.js | Server-side rendering with hydration |
| `__NUXT__` or `__NUXT_DATA__` in page | Nuxt.js | Vue SSR framework |

### Framework-Specific Interaction Tips

**React apps:**
- State updates are batched — wait 500ms-2s after interactions for re-renders
- Look for `data-testid` attributes (common in React Testing Library projects)
- Portal-rendered content (modals, tooltips) may be at the end of `<body>`, not nested in the component tree
- React-Select dropdowns: click the container, then look for `[class*="option"]` in the menu that appears

**Vue apps:**
- `v-if` elements may not exist in DOM until conditions are met — re-read page after state changes
- Vue transitions: wait for CSS transitions to complete before interacting
- Vuetify/Element UI components have predictable class prefixes (`.v-btn`, `.el-input`)

**Angular apps:**
- Elements often have `_ngcontent-` or `_nghost-` attributes (do not use these as selectors — they change per build)
- Angular Material components: use `[role]` and `[aria-label]` attributes instead of classes
- Forms may use reactive validation — errors appear only after interaction (`blur` event)

**General SPA rules:**
- After clicking a navigation element, wait 1-3 seconds before reading the page
- If content is missing, check for loading indicators: `.loading`, `.spinner`, `[aria-busy="true"]`, `.skeleton`
- Retry `browser_read_page` up to 3 times with 2-second intervals before giving up
- URL changes without full page reload confirm SPA routing — do not expect `browser_navigate` events

## Site-Specific Selector Patterns

These are reference selectors for common sites. They change frequently — always verify with `browser_read_page` if a selector fails, then construct a fresh selector from the live DOM.

### Google Search
| Element | Selector |
|---------|----------|
| Search input | `input[name="q"]`, `textarea[name="q"]` |
| Search button | `input[name="btnK"]`, `button[type="submit"]` |
| Result titles | `h3` (within `#search`) |
| Result links | `#search a[href^="http"]` |
| "Next" pagination | `a#pnnext` |

### Amazon
| Element | Selector |
|---------|----------|
| Search input | `#twotabsearchtextbox` |
| Search button | `#nav-search-submit-button` |
| Add to cart | `#add-to-cart-button` |
| Quantity dropdown | `#quantity` |
| Cart count | `#nav-cart-count` |

### GitHub
| Element | Selector |
|---------|----------|
| Search | `input[name="q"]` |
| Repository name | `[itemprop="name"] a` |
| Star button | `button[aria-label*="Star"]` |
| Submit button | `button[type="submit"]` |

Note: When a saved selector fails, use `browser_read_page` to discover the current DOM, then build a new selector from live content. Prefer `[data-testid]`, `[aria-label]`, or visible text over fragile class-based selectors.

---

## Common Workflows

### Product Search & Purchase
```
1. browser_navigate → store homepage
2. browser_type → search box with product name
3. browser_click → search button or press Enter
4. browser_read_page → scan results
5. browser_click → desired product
6. browser_read_page → verify product details & price
7. browser_click → "Add to Cart"
8. browser_navigate → cart page
9. browser_read_page → verify cart contents & total
10. STOP → Report to user, wait for approval
11. browser_click → "Proceed to Checkout" (only after approval)
```

### Account Login
```
1. browser_navigate → login page
2. browser_read_page → identify form fields and any CAPTCHA
3. browser_type → email/username field
4. browser_type → password field
5. browser_click → login/submit button
6. browser_read_page → verify successful login (check for dashboard/profile elements)
7. If MFA required → inform user, wait for code input
```

### Form Submission
```
1. browser_navigate → form page
2. browser_read_page → understand form structure
3. browser_type → fill each field sequentially
4. browser_click → checkboxes/radio buttons as needed
5. browser_screenshot → visual verification before submit
6. browser_click → submit button
7. browser_read_page → verify confirmation
```

### Price Comparison
```
1. For each store:
   a. browser_navigate → store URL
   b. browser_type → search query
   c. browser_read_page → extract prices
   d. memory_store → save price data
2. memory_recall → compare all prices
3. Report findings to user
```

### Multi-Page Data Extraction
```
1. browser_navigate → starting page
2. browser_read_page → extract data from current page
3. memory_store → save extracted data
4. Check for pagination:
   a. browser_click → "Next" button or page number link
   b. browser_read_page → verify new page loaded (check for changed content)
   c. Repeat from step 2
5. If no more pages → compile and report results
```

### Account Registration
```
1. browser_navigate → registration page
2. browser_read_page → identify required fields
3. browser_type → fill name, email, password fields sequentially
4. browser_click → accept terms checkbox (if required)
5. browser_screenshot → verify all fields before submission
6. browser_click → submit/register button
7. browser_read_page → check for:
   - Success page → registration complete
   - Email verification prompt → inform user
   - Validation errors → read errors, correct fields, retry
```

### File Download Monitoring
```
1. browser_navigate → page with download link
2. browser_read_page → identify download button/link
3. browser_click → download trigger
4. browser_read_page → check for download confirmation or redirect
5. If download requires additional steps (accept terms, choose format):
   a. browser_click → required selections
   b. browser_click → final download button
6. Report download status to user
```

---

## Wait Strategies & Timing

### When to Wait
Proper waiting prevents most automation failures. Never use fixed sleep times when a condition-based wait is possible.

| Scenario | Strategy | Notes |
|----------|----------|-------|
| Page navigation | Wait for load event | `browser_navigate` handles this automatically |
| After clicking link | Read page to confirm new content | Check for expected elements on destination |
| AJAX/dynamic content | Re-read page after delay | Some SPAs load content asynchronously |
| Form submission | Read page for confirmation | Check for success message or redirect |
| Slow networks | Retry with backoff | 3s, 6s, 12s intervals |
| Animation/transition | Brief pause before interaction | Modal fade-in, dropdown expansion |

### Detecting Page Load Completion
```
After browser_navigate or browser_click that triggers navigation:
1. browser_read_page → check if expected content is present
2. If content missing → wait 2-3 seconds → browser_read_page again
3. If still missing after 3 retries → page may have changed structure
4. Use browser_screenshot to visually confirm page state
```

### SPA (Single Page Application) Handling
SPAs (React, Angular, Vue, Svelte) do not trigger traditional page loads. Client-side routing means the browser URL changes but no network navigation occurs.

```
1. browser_click → triggers route change (URL updates but no page reload)
2. browser_read_page → may return stale content from previous view
3. Check for loading indicators in the output:
   - Text: "Loading...", "Please wait", skeleton placeholders
   - Attributes: [aria-busy="true"]
   - Classes: .loading, .spinner, .skeleton, .placeholder
4. If loading detected OR content stale → wait 2 seconds
5. browser_read_page → retry (attempt 2 of 3)
6. If still stale → wait 3 seconds → browser_read_page (attempt 3 of 3)
7. If content never updates:
   a. browser_screenshot → check if content is visually present but not captured as text
   b. The content may be inside an iframe or shadow DOM — try alternative access
   c. Report the issue to the user with the screenshot
```

### Iframe Content Access
```
When target content is inside an iframe:
1. browser_read_page → look for <iframe> elements and their src attributes
2. browser_navigate → directly to the iframe src URL (if same-origin)
3. Interact with the content normally
4. browser_navigate → back to the parent page when done
Note: Cross-origin iframes may block direct access. Inform the user if this occurs.
```

### Shadow DOM Awareness
```
Web components using shadow DOM hide their internals from normal CSS selectors:
1. If a known element is not found by any selector, suspect shadow DOM
2. browser_screenshot → visually confirm the element exists on the page
3. Try interacting via visible text content (may pierce shadow boundaries)
4. If interaction fails, inform the user that the element is inside a shadow root
```

---

## Error Recovery Strategies

### Error Recovery Decision Tree
When any interaction fails, walk through this decision tree top-to-bottom:

```
INTERACTION FAILED
│
├─ Is this the correct page?
│  ├─ NO → browser_read_page to check URL
│  │       ├─ Redirected to login? → re-authenticate, then retry
│  │       ├─ Redirected to error page? → handle HTTP error (see below)
│  │       └─ Wrong page entirely? → browser_navigate to correct URL
│  └─ YES ↓
│
├─ Is an overlay blocking the element?
│  ├─ YES → dismiss overlay (cookie banner, modal, chat widget)
│  │        then retry the original interaction
│  └─ NO ↓
│
├─ Does the element exist in the DOM?
│  ├─ NO → page may not have finished rendering
│  │       ├─ Wait 2 seconds → browser_read_page → retry (up to 3 times)
│  │       ├─ Scroll the page to trigger lazy loading → retry
│  │       ├─ Try alternative selectors (see priority order below)
│  │       └─ Still not found? → browser_screenshot → report to user
│  └─ YES ↓
│
├─ Is the element visible and interactive?
│  ├─ Disabled ([disabled], [aria-disabled="true"]) → inform user, cannot interact
│  ├─ Hidden (display:none, off-screen) → may be inside collapsed section, try expanding
│  ├─ Covered by another element → identify and dismiss the covering element
│  └─ YES ↓
│
├─ Did the click/type register?
│  ├─ NO → JavaScript may not have attached handlers yet
│  │       ├─ Wait 2 seconds → retry
│  │       ├─ Try clicking a more specific child element
│  │       └─ Try clicking by visible text instead of CSS selector
│  └─ YES ↓
│
└─ Did the expected state change occur?
   ├─ NO → SPA may need time to re-render
   │       ├─ Wait 2-3 seconds → browser_read_page to verify
   │       ├─ Check for loading indicators ([aria-busy], .spinner)
   │       └─ After 3 retries, browser_screenshot → report to user
   └─ YES → continue to next step
```

### Selector Fallback Order
When the primary selector fails, try alternatives in this order:
```
1. [data-testid="..."], [data-test="..."], [data-cy="..."]  — test attributes
2. [aria-label="..."], [role="button"]                       — accessibility
3. Visible text content: a:has-text("Sign In")               — human-readable
4. input[name="..."], input[type="..."]                      — form semantics
5. #id                                                        — unique ID
6. [class*="keyword"]                                         — partial class match (last resort)
```

### Quick Reference
| Error | Recovery |
|-------|----------|
| Element not found | Walk selector fallback order, scroll page, screenshot |
| Page timeout | Retry URL once, try base domain, report to user |
| Login required | Inform user, ask for credentials |
| CAPTCHA | Screenshot and inform user — cannot solve |
| Pop-up/modal | Dismiss first, then retry original action |
| Cookie consent | Click "Accept All" or dismiss banner |
| Rate limited (429) | Wait 30s, retry; after 3 failures, stop and report |
| Session expired | Detect login redirect, re-authenticate, resume |
| Wrong page | Verify URL, navigate back or to correct page |
| Empty SPA content | Wait 3-5s for render, retry read up to 3 times |

### Navigation Failure Recovery
```
1. Timeout on browser_navigate:
   a. Retry the same URL once
   b. If still fails, check if URL is valid (no typos, correct protocol)
   c. Try simplified URL (remove query params, try base domain)
   d. Report connectivity issue to user

2. Unexpected redirect:
   a. browser_read_page → check current URL and content
   b. If redirected to login → handle login flow
   c. If redirected to error page → report the error code and message
   d. If redirected to different page → assess if it is relevant, otherwise navigate back

3. HTTP errors observed in page content:
   - 403 Forbidden → site may be blocking automation, inform user
   - 404 Not Found → URL is stale or incorrect, try searching for the correct page
   - 429 Too Many Requests → wait 60 seconds, retry with longer intervals
   - 500/502/503 → server issue, retry after 30 seconds (max 3 retries)
```

### Stale Element Recovery (SPA-Specific)
Elements become stale when the page re-renders — common in React, Vue, and Angular:
```
1. Identify the stale interaction (click that produced no result or error)
2. browser_read_page → get fresh DOM snapshot
3. Check if the element's selector still matches in the new DOM
4. If not, construct a new selector from the fresh page content
5. Retry the interaction with the updated selector
6. If element has moved, use browser_screenshot to find its new location
```

### Pop-up and Overlay Dismissal
```
Order of priority when overlays block interaction:
1. Cookie consent banners:
   - Selectors: [aria-label*="cookie" i] button, #onetrust-accept-btn-handler
   - Text: "Accept All", "Accept Cookies", "Agree", "OK", "Got it"
   - Fallback: .cookie-banner .close, #cookie-close, [aria-label="Close"]

2. Newsletter/subscription modals:
   - Selectors: [role="dialog"] [aria-label="Close"], .modal .close, button.dismiss
   - Fallback: press Escape key (via browser_type on body element)

3. Chat widgets:
   - Usually do not block (z-index layer); if blocking, click minimize/close

4. Age verification gates:
   - Click "Yes" / "I am over 18" / "Enter"
   - May need to select a birth date from dropdowns

5. App install banners:
   - Look for "Continue in browser", "Not now", or close/dismiss buttons

6. Browser-level permission prompts:
   - Auto-dismissed by Playwright context settings
```

---

## Anti-Detection Techniques

### Behavioral Patterns
Automation detection looks for non-human interaction patterns. Mitigate by:
```
1. TIMING: Do not interact instantly after page load
   - Wait 1-3 seconds before first interaction
   - Insert 0.5-2 second gaps between form field entries
   - Vary timing (not perfectly uniform intervals)

2. NAVIGATION: Follow natural browsing patterns
   - Visit homepage before deep URLs when possible
   - Click through navigation instead of using direct URLs
   - Scroll before interacting with below-the-fold content

3. INPUT: Simulate realistic behavior
   - Type character by character (browser_type handles this)
   - Click buttons rather than submitting forms programmatically
   - Do not fill hidden honeypot fields (see below)
   - Do not request pages faster than 1 per 3 seconds on the same domain
```

### Honeypot Field Detection
```
Do NOT fill fields that have:
  - style="display: none" or style="visibility: hidden"
  - class="hidden", class="d-none", class="sr-only"
  - type="hidden" (unless it is a legitimate CSRF token or form ID)
  - Position: absolute with left: -9999px (off-screen placement)

Use browser_read_page to inspect field visibility before filling.
```

---

## Screenshot & Content Extraction

### When to Take Screenshots
| Situation | Purpose |
|-----------|---------|
| Before form submission | Visual verification of filled data |
| After login attempt | Confirm success or capture error state |
| When element not found | See actual page state for debugging |
| Price/product comparison | Visual record for user |
| CAPTCHA encountered | Show user what needs solving |
| Before financial transaction | Proof of cart/payment details |
| Unexpected page state | Diagnose navigation or rendering issues |

### Content Extraction Patterns
```
Tables:  browser_read_page → identify table boundaries → parse rows/columns → memory_store
Data:    browser_read_page → search for labels ("Price:", "In Stock", "Rating:") → extract adjacent values
Dynamic: browser_read_page → if "Loading..." or skeleton → wait 2-3s → retry
Scroll:  extract visible data → scroll down → browser_read_page → repeat until complete (max 10 cycles)
```

---

## Form Filling & Interaction Sequences

### Dropdown / Select Menus
```
Standard HTML <select>:
  browser_click → the <select> element to open it
  browser_click → the <option> with desired value

Custom dropdown (div-based):
  1. browser_click → the dropdown trigger element (.dropdown-toggle, .select-wrapper)
  2. browser_read_page → find the dropdown options that appeared
  3. browser_click → the desired option from the expanded list
```

### Date Pickers
```
Native HTML date input (input[type="date"]):
  browser_type → the date value in YYYY-MM-DD format directly into the input

Custom calendar widget:
  1. browser_click → date input to open calendar
  2. browser_click → month/year navigation arrows to reach target month
  3. browser_click → the target day cell
  4. browser_read_page → verify selected date
```

### File Uploads
```
Standard file input (input[type="file"]):
  - Playwright can set file input values directly
  - Not always available via browser_type — inform user if upload needed

Drag-and-drop upload zones:
  - Usually have a fallback "Browse files" button/link
  - browser_click → "Browse" or "Choose file" fallback button
```

### Multi-Step Forms (Wizards)
```
1. browser_read_page → identify current step and total steps
2. Fill current step fields with browser_type and browser_click
3. browser_click → "Next" / "Continue" button
4. browser_read_page → verify progression to next step
5. If validation error appears:
   a. browser_read_page → identify error messages
   b. Fix the flagged fields
   c. browser_click → "Next" again
6. Repeat until final step
7. browser_screenshot → capture summary/review page
8. STOP → get user approval before final submission
```

### Autocomplete / Typeahead Fields
```
1. browser_type → partial text into the input field
2. Wait 1-2 seconds for suggestion dropdown to appear
3. browser_read_page → check if suggestions loaded
4. browser_click → the desired suggestion from the dropdown
5. browser_read_page → verify the field populated correctly
```

### Checkbox and Radio Button Groups
```
Checkboxes (multi-select):
  browser_click → each desired checkbox
  Use browser_read_page to check current state ([checked] attribute)
  Do NOT click already-checked boxes unless intending to uncheck

Radio buttons (single-select):
  browser_click → the desired option
  Only one can be active — clicking a new one deselects the previous
```

---

## Multi-Tab and Popup Handling

### Links That Open New Tabs
```
When browser_click opens a new tab (target="_blank" links):
1. The new tab becomes the active context
2. browser_read_page → verify content in new tab
3. Complete actions in the new tab
4. browser_close → close the new tab to return to the original
5. browser_read_page → verify original tab is still in expected state
```

### Authentication Popups (OAuth, SSO)
```
OAuth/Social login flows often open a popup:
1. browser_click → "Sign in with Google/GitHub/etc."
2. New popup/tab opens with the provider's login page
3. browser_type → credentials in the popup
4. browser_click → authorize/allow button
5. Popup closes automatically, original page refreshes
6. browser_read_page → verify login success on original page
```

### Multiple Window Coordination
```
When workflow requires information from multiple pages:
1. Open first page → extract needed data → memory_store
2. browser_navigate → second page (replaces current)
3. Extract data from second page → memory_store
4. Use memory_recall to combine data from both sources
5. browser_navigate → return to original page if needed

Avoid keeping multiple tabs open simultaneously when possible —
single-tab workflows are more reliable and predictable.
```

---

## Cookie and Session Management

### Session Persistence
```
Playwright browser sessions persist cookies within a single session:
- Logging in once is enough for subsequent navigations to the same site
- Cookies expire when the browser context is closed (browser_close)
- For long workflows, periodically verify session is still active:
  1. browser_navigate → a page that requires authentication
  2. browser_read_page → check for login page redirect
  3. If redirected to login → session expired, re-authenticate
```

### Cookie Consent Handling
```
Most sites display cookie banners on first visit. Handle immediately:
1. browser_read_page → check for cookie banner presence
2. Look for accept buttons with these common selectors:
   - #cookie-accept, #accept-cookies, #onetrust-accept-btn-handler
   - button[data-action="accept"], .cookie-consent .accept
   - Text content: "Accept All", "Accept Cookies", "I Agree", "OK"
3. browser_click → the accept button
4. browser_read_page → verify banner dismissed
5. If banner persists → try clicking the close/X button instead
```

### Geo-Restricted Content
```
When content varies by location:
1. browser_read_page → check for location selection prompts
2. If location selector present:
   a. browser_click → country/region dropdown
   b. browser_click → desired country/region
   c. browser_read_page → verify content updated for selected region
3. Some sites redirect to country-specific domains (.co.uk, .de, etc.)
   - Navigate directly to the correct country domain
```

---

## Performance Optimization

### Minimizing Page Reads
```
browser_read_page is the most expensive operation (returns full page text).
Optimize by:
1. Use browser_read_page once after navigation, extract ALL needed data
2. Use browser_screenshot for quick visual checks instead of full reads
3. After clicking a button, only read the page if you need to verify
   the result or extract new data
4. Cache page content in memory_store if you will reference it later
```

### Efficient Navigation
```
1. Use direct URLs when possible instead of click-through navigation:
   BAD:  homepage → click "Products" → click "Electronics" → click "Phones"
   GOOD: browser_navigate → /products/electronics/phones

2. Use URL patterns for pagination:
   If page 1 is /results?page=1, go directly to /results?page=5
   instead of clicking "Next" five times

3. Combine operations:
   Instead of: navigate → read → navigate → read → navigate → read
   Use: navigate → read + extract all → navigate next → read + extract all
```

### Handling Lazy-Loaded Content
```
Many modern sites load content as the user scrolls (infinite scroll):
1. browser_read_page → get initially loaded content
2. If you need more items:
   a. browser_click → a far-down element to trigger scroll loading
   b. Wait 2-3 seconds for new content to render
   c. browser_read_page → extract newly loaded content
   d. Repeat until sufficient data collected
3. Set a maximum iteration count (e.g., 10 scroll cycles)
   to prevent infinite loops on endlessly scrolling pages
```

### Rate Limiting Awareness
```
Respect site rate limits to avoid IP blocks:
- Space requests to same domain by at least 2-3 seconds
- If you receive a 429 error or see "Too many requests":
  1. Wait 30-60 seconds before next request
  2. Double the wait time on each subsequent 429
  3. After 3 consecutive 429s, inform user and stop
- Watch for soft rate limiting signals:
  - CAPTCHA appearing mid-session
  - Results becoming empty or different
  - Redirect to a "verify you are human" page
```

---

## Common Failure Modes & Debugging

### Diagnosis Checklist
When an interaction fails, check in this order:
```
1. CORRECT PAGE?
   browser_read_page → confirm you are on the expected URL/page

2. ELEMENT EXISTS?
   browser_read_page → search output for the target element's text or nearby text

3. ELEMENT VISIBLE?
   browser_screenshot → check if element is visible (not behind overlay, not off-screen)

4. ELEMENT BLOCKED?
   Look for cookie banners, modals, chat widgets covering the element

5. ELEMENT INTERACTIVE?
   Check if element is disabled, greyed out, or read-only

6. PAGE FULLY LOADED?
   Look for loading indicators in page content (spinner text, "Loading...")

7. SESSION VALID?
   Check if you have been redirected to a login page
```

### Common Failure Patterns

**Clicking does nothing:**
```
Causes:
  - Element is covered by an overlay (cookie banner, modal)
  - Element is outside the viewport (needs scroll)
  - Element is disabled or has pointer-events: none
  - JavaScript click handler has not attached yet (page still loading)
  - Clicking on a wrapper div instead of the actual button

Fixes:
  1. Dismiss any overlays first
  2. Scroll to the element before clicking
  3. Wait 2 seconds and retry
  4. Try a more specific selector targeting the inner clickable element
```

**Form submission fails silently:**
```
Causes:
  - Required field left empty (client-side validation blocked submit)
  - Hidden honeypot field was filled (bot detection)
  - CSRF token expired (session timeout)
  - JavaScript form validation prevents submission

Fixes:
  1. browser_read_page → check for inline validation error messages
  2. browser_screenshot → look for highlighted required fields
  3. Verify all required fields are filled (check for asterisks or "required" labels)
  4. Try refreshing the page and filling the form again (new CSRF token)
```

**Page content appears empty or minimal:**
```
Causes:
  - Site requires JavaScript rendering (content injected by React/Vue/Angular)
  - Content is behind an authentication wall
  - Site is geo-blocked or IP-blocked
  - Content loads via AJAX after initial page load

Fixes:
  1. Wait 3-5 seconds after navigation, then browser_read_page
  2. browser_screenshot → check if content is visually present but not in text
  3. Check if login is required
  4. Try a different URL or approach
```

**Redirect loop or unexpected page:**
```
Causes:
  - Session expired → site redirects to login → tries to redirect back → loop
  - Geo-redirect based on IP location
  - A/B testing serves different page version
  - Site requires cookie acceptance before showing content

Fixes:
  1. browser_read_page → check current URL
  2. Handle cookie consent if prompted
  3. Re-authenticate if on login page
  4. Try navigating to the base domain first, then to the target page
```

---

## Security Checklist

### Before Entering Credentials
- Verify the domain matches the expected site (check for typosquatting)
- Confirm the page is served over HTTPS
- Look for suspicious elements (extra fields, unusual layout)
- Never enter credentials on HTTP pages
- Warn user about any certificate warnings or security indicators

### During Sensitive Operations
- Never store passwords in memory_store — use them only in browser_type
- Never auto-approve financial transactions — always STOP and confirm with user
- Report any unexpected redirects during authentication
- Log out of sessions when workflow is complete

### Phishing Indicators to Watch For
| Indicator | Example | Action |
|-----------|---------|--------|
| Misspelled domain | amaz0n.com, gooogle.com | STOP and warn user |
| Unusual TLD | amazon.xyz, paypal.ru | STOP and warn user |
| HTTP on login page | http://bank.com/login | STOP and warn user |
| Extra form fields | SSN on a retail login | STOP and warn user |
| Suspicious redirects | Login redirects to different domain | STOP and warn user |
| Urgency language | "Account suspended, act now" | Inform user, suggest verifying |

### Data Handling Rules
```
SAFE to store in memory_store:
  - Product names, prices, descriptions
  - Public profile information
  - Search results and comparisons
  - Order confirmation numbers
  - Non-sensitive form field values

NEVER store in memory_store:
  - Passwords, PINs, security codes
  - Credit card numbers or CVVs
  - Social Security or government ID numbers
  - Authentication tokens or session cookies
  - Private messages or confidential communications
```